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Reference Information 



This section contains reference information about the HP Motif environment. The entries 
are arranged alphabetically, with each entry beginning on its own "page 1." 
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NAME 

mwm - The OSF/Motif Window Manager. 

SYNOPSIS 

mwm [options] 

DESCRIPTION 

The OSF/Motif Window Manager (mwm) is an Xll client that provides window management 
functionality and some session management functionality. It provides functions that facilitate con- 
trol (by the user and the programmer) of elements of window states such as placement, size, 
icon/normal display, input focus ownership, etc. It also provides session management functions 
such as stopping a client. 

OPTIONS 

-display display 

This option specifies the display to use; see X(l). 

-xrm resourcestring 

This option specifies a resource string to use. 



APPEARANCE 

The following sections describe the basic default behaviors of windows, icons, the icon box, input 
focus, and window stacking. The appearance and behavior of the window manager can be altered 
by changing the configuration of specific resources. Resources are defined under the heading "X 
DEFAULTS." 



WINDOWS 

Default mwm window frames have distinct components with associated functions: 

Title Area In addition to displaying the client's title, the title area is used to move 

the window. To move the window, place the pointer over the title area, 
press button 1 and drag the window to a new location. A wire frame is 
moved during the drag to indicate the new location. When the button 
is released, the window is moved to the new location. 



Title Bar 



Minimize Button 



Maximize Button 



Window Menu Button 



The title bar includes the title area, the minimize button, the maximize 
button and the window menu button. 

To turn the window back into its icon, do a button 1 click on the minim- 
ize button (the frame box with a small square in it). 

To make the window fill the screen (or enlarge to the largest size 
allowed by the configuration files), do a button 1 click on the maximize 
button (the frame box with a large square in it). 

The window menu button is the frame box with a horizontal bar in it. 
To pop up the window menu, press button 1. While pressing, drag the 
pointer on the menu to your selection, then release the button when 
your selection is highlighted. Alternately, you can click button 1 to pop 
up the menu and keep it posted; then position the pointer and select. 
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Default Window Menu 


Selection 


Accelerator 


Description 


Restore 


Alt+ES 


Inactive (not an option for windows). 


Move 


AU+F7 

Shift + Move Grow 


Allows the window to be moved with keys 
or mouse. 
Apollo keyboard. 


Size 


AU+F8 
Move Grow 


Allows the window to be resized. 
Apollo keyboard. 


Minimize 


AU+F9 
Shift + Pop 


Turns the window into an icon. 
Apollo keyboard. 


Maximize 


Alt+FlO 

Ctrl + Move Grow 


Makes the window fill the screen. 
Apollo keyboard. 


Lower 


Alt+F3 


Moves window to bottom of window 
stack. 


Close 


Alt+F4 


Removes client from MWM management. 



Resize Border Handles To change the size of a window, move the pointer over a resize border 
handle (the cursor will change), press button 1, and drag the window to 
a new size. When the button is released, the window is resized. While 
dragging is being done, a rubber-band outline is displayed to indicate 
the new window size. 

Matte An optional matte decoration can be added between the client area and 

the window frame. A matte is not actually part of the window frame. 
There is no functionality associated with a matte. 

ICONS 

Icons are small graphic representations of windows. A window can be minimized (iconified) using 
the minimize button on the window frame. Icons provide a way to reduce clutter on the screen. 

Pressing mouse button 1 when the pointer is over an icon will cause the icon's window menu to 
pop up. Releasing the button (press + release without moving mouse = click) will cause the 
menu to stay posted. The menu contains the following selections: 
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Icon Window Menu 


Selection 


Accelerator 


Description 


Restore 


Alt+ES 
Shift + Pop 


Opens the associated window. 
Apollo keyboard. 


Move 


Alt+F7 

Shift + Move Grow 


Allows the icon to be moved with 
keys. 

Apollo keyboard. 


Size 


Alt+F8 


Inactive (not an option for icons). 


Minimize 


Alt+F9 


Inactive (not an option for icons). 


Maximize 


Alt+FlO 
Qrl + Pop 


Opens the associated window and 
makes it fill the screen. 
Apollo keyboard. 


Lower 


Alt+F3 


Moves icon to bottom of icon 
stack. 


Close 


Alt+F4 


Removes client from MWM 
management. 



Double-clicking button 1 on an icon normalizes the icon into its associated window. Double- 
clicking button 1 on the icon box's icon opens the icon box and allow access to the contained icons. 
(In general, double-clicking a mouse button offers a quick way to have a function performed. 
Another example is double-clicking button 1 with the pointer on the window menu button. This 
closes the window.) 

ICON BOX 

When icons begin to clutter the screen, they can be packed into an "icon box." (To use an icon 
box, MWM must be started with the icon box configuration already set.) The icon box is a window 
manager window that holds client icons. Icons in the icon box can be manipulated with the 
mouse. The following table summarizes the behavior of this interface. Button actions apply 
whenever the pointer is on any part of the icon. 



Button Action 


Description 


Button 1 click 


Selects the icon. 


Button 1 double click 


Normalizes (opens) the associated window. 


Button 1 double click 


Raises an already open window 
to the top of the stack. 


Button 1 drag 


Moves the icon. 



The window menu of the icon box differs from the window menu of a client window: The "Close" 
selection is replaced with the "Packlcons Alt+F12" selection. When selected, Packlcons packs the 
icons in the box to achieve neat rows with no empty slots. 

INPUT FOCUS 

Mwm supports (by default) a keyboard input focus policy of explicit selection. This means when a 
window is selected to get keyboard input, it continues to get keyboard input until the window is 
withdrawn from window management, another window is explicitly selected to get keyboard input, 
or the window is iconified. There are numerous resources that control the input focus. The client 
window with the keyboard input focus has the active window appearance with a visually distinctive 
window frame. 

The following tables summarize the keyboard input focus selection behavior 



Button Action 


Object 


Function Description 


Button 1 press 


Window /window frame 


Keyboard focus selection 


Button 1 press 


Icon 


Keyboard focus selection 
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Key Action 


Function Description 


[Alt][Tab] 
[Next Wndw] 


Move input focus to next window in window stack. 
Apollo keyboard. 


[Alt][Shift][Tab] 
[Shift][Next Whdw] 


Move input focus to previous window in window stack. 
Apollo keyboard. 



WINDOW STACKING 

The stacking order of windows may be changed as a result of setting the keyboard input focus, 
iconifying a window, or by doing a window manager window stacking function. 

When a window is iconified, the window's icon is placed on the bottom of the stack. 

The following table summarizes the default window stacking behavior of the window manager 



Key Action 


Function Description 


[Alt][ESq 
[Qrl][Pop] 


Put bottom window on top of stack. 
Apollo keyboard. 


[Alt][Shift][ESq 
[Alt][Pop] 


Put top window on bottom of stack. 
Apollo keyboard. 


[Pop] 


Apollo keyboard. Put bottom window on top 
of stack; put top window on bottom of stack. 



A window can also be raised to the top when it gets the keyboard input focus (e.g., by doing a but- 
ton 1 press on the window or by using [Alt]|Tab]) if this auto-raise feature is enabled with the 
focusAutoRaise resource. 

X DEFAULTS 

Mwm is configured from its resource database. This database is built from the following sources. 
They are listed in order of precedence, low to high: 

app-defaults/Mwm 

RESOURCEMANAGER root window property or $HOME/.Xdefaults 
XENVIRONMENT variable or $HOME/.Xdefaults-host 
mwm command line options 

Entries in the resource database may refer to other resource files for specific types of resources. 
These include files that contain bitmaps, fonts, and mwm specific resources such as menus and 
behavior specifications (i.e., button and key bindings). 

Mwm is the resource class name of mwm and mwm is the resource name used by mwm to look up 
resources. In the following discussion of resource specification "Mwm" and "mwm" can be used 
interchangeably. 

Mwm uses the following types of resources: 
Component Appearance Resources: 

These resources specify appearance attributes of window manager user interface components. 
They can be applied to the appearance of window manager menus, feedback windows (e.g., the 
window reconfiguration feedback window), client window frames, and icons. 

Specif ic Appearance and Behavior Resources: 

These resources specify mwm appearance and behavior (e.g., window management policies). 
They are not set separately for different mwm user interface components. 

Client Specific Resources: 

These mwm resources can be set for a particular client window or class of client windows. They 
specify client-specific icon and client window frame appearance and behavior. 

Resource identifiers can be either a resource name (e.g., foreground) or a resource class (e.g., 
Foreground). If the value of a resource is a filename and if the filename is prefixed by ""/", then 
it is relative to the path contained in the $HOME environment variable (generally the user's home 
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directory). This is the only environment variable mwm uses directly (SXENVIRONMENT is used 
by the resource manager). 

COMPONENT APPEARANCE RESOURCES 

The syntax for specifying component appearance resources that apply to window manager icons, 
menus, and client window frames is 

Mwm*resourceJd 

For example, Mwm*foreground is used to specify the foreground color for mwm menus, icons, 
and client window frames. 

The syntax for specifying component appearance resources that apply to a particular mwm com- 
ponent is 

Mwm*[menu | icon | client | teedback]*resource_id 

If menu is specified, the resource is applied only to mwm menus; if icon is specified, the resource 
is applied to icons; and if client is specified, the resource is applied to client window frames. For 
example, Mwm*icon*foreground is used to specify the foreground color for mwm icons, 
Mwm*menu*foreground specifies the foreground color for mwm menus, and 
Mwm*client*foreground is used to specify the foreground color for mwm client window frames. 

The appearance of the title area of a client window frame (including window management but- 
tons) can be separately configured. The syntax for configuring the title area of a client window 
frame is: 

Mwm*cUent*title*Hes0wrce_itf 

For example, Mwm*client*title*foreground specifies the foreground color for the title area. 
Defaults for title area resources are based on the values of the corresponding client window frame 
resources. 

The appearance of menus can be configured based on the name of the menu. The syntax for 
specifying menu appearance by name is: 

Mwm*menu*menu_name*resource_id 

For example, Mwm*menu*my_menu*foreground specifies the foreground color for the menu 
named mymenu. 

The following component appearance resources that apply to all window manager parts can be 
specified: 
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Component Appearance Resources - All Window Manager Farts 


Name 


Class 


Value Type 


Default 


background 


Background 






backgroundPixiiiap 




string** 


varies* 


bottomShadowColor 


Foreground 


color 


varies* 


bottomShadowPixmap 


BottomShadowPixmap 


string** 


varies* 


font List 


FontList 


string*** 


"fixed" 


foreground 


Foreground 


color 


varies* 


saveUnder 


SaveUnder 


T/F 


F 


topShadowColor 


Background 


color 


varies* 


topShadowPixmap 


TopShadowPixmap 


string** 


varies* 



*The default is chosen based on the visual type of the screen. **Pixmap image name. See XmInstallImage(3X). 
***X11 R3 Font description. 



background (class Background) 

This resource specifies the background color. Any legal X color may be specified. The 
default value is chosen based on the visual type of the screen. 

background Pixmap (class BackgroundPixmap) 

This resource specifies the background Pixmap of the mwm decoration when the window 
is inactive (does not have the keyboard focus). The default value is chosen based on the 
visual type of the screen. 

bottomShadowColor (class Foreground) 

This resource specifies the bottom shadow color. This color is used for the lower and 
right bevels of the window manager decoration. Any legal X color may be specified. The 
default value is chosen based on the visual type of the screen. 

bottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap. This Pixmap is used for the lower 
and right bevels of the window manager decoration. The default is chosen based on the 
visual type of the screen. 

fontList (class Font) 

This resource specifies the font used in the window manager decoration. The character 
encoding of the font should match the character encoding of the strings that are used. 
The default is "fixed." 

foreground (class Foreground) 

This resource specifies the foreground color. The default is chosen based on the visual 
type of the screen. 

saveUnder (class SaveUnder) 

This is used to indicate whether "save unders" are used for mwm components. For this 
to have any effect, save unders must be implemented by the X server. If save unders are 
implemented, the X server will save the contents of windows obscured by windows that 
have the save under attribute set If the saveUnder resource is True, mwm will set the 
save under attribute on the window manager frame of any client that has it set. If 
saveUnder is False, save unders will not be used on any window manager frames. The 
default value is False. 

topShadowColor (class Background) 

This resource specifies the top shadow color. This color is used for the upper and left 
bevels of the window manager decoration. The default is chosen based on the visual type 
of the screen. 

topShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap. This Pixmap is used for the upper and 
left bevels of the window manager decoration. The default is chosen based on the visual 
type of the screen. 
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The following component appearance resources that apply to frame and icons can be specified: 



Frame and Icon Components 


Name 


Class 


Value Type 


Default 


activeBackgroimd 


Background 


color 


varies* 


activeBackgroundPixmap 


BackgroundPixmap 


string** 


varies* 


activeBottomSbadowColor 


Foreground 


color 


varies* 


activeBottomSbadowPixmap 


BottomShadowPixmap 


string** 


varies* 


activeForeground 


Foreground 


color 


varies* 


activeTopShadowColor 


Background 


color 


varies* 


actweTopShadowPixmap 


TopShadowPixmap 


string** 


varies* 



*The default is chosen based on the visual type of the screen. **See XmInstallImage(3X). 



activeBackgrou nd (class Background) 

This resource specifies the background color of the mwm decoration when the window is 
active (has the keyboard focus). The default is chosen based on the visual type of the 
screen. 

activeBackgroundPixmap (class ActiveBackgroundPixmap) 

This resource specifies the background Pixmap of the mwm decoration when the window 
is active (has the keyboard focus). The default is chosen based on the visual type of the 
screen. 

activeBottomShadowCoIor (class Foreground) 

This resource specifies the bottom shadow color of the mwm decoration when the win- 
dow is active (has the keyboard focus). The default is chosen based on the visual type of 
the screen. 

activeBottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the mwm decoration when the win- 
dow is active (has the keyboard focus). The default is chosen based on the visual type of 
the screen. 

activeForeground (class Foreground) 

This resource specifies the foreground color of the mwm decoration when the window is 
active (has the keyboard focus). The default is chosen based on the visual type of the 
screen. 

activeTopShadowColor (class Background) 

This resource specifies the top shadow color of the mwm decoration when the window is 
active (has the keyboard focus). The default is chosen based on the visual type of the 
screen. 

activeTopShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the mwm decoration when the window 
is active (has the keyboard focus). The default is chosen based on the visual type of the 
screen. 

SPECIFIC APPEARANCE AND BEHAVIOR RESOURCES 

The syntax for specifying specific appearance and behavior resources is 

Mwm*resource_id 

For example, Mwm*keyboardFocusPolicy specifies the window manager policy for setting the key- 
board focus to a particular client window. 

The following specific appearance and behavior resources can be specified: 
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Specific Appearance and Behavior Resources 




Class 


Value lype 


Default 


autoKeyFocus 


AutoKeyFocus 


T/F 


T 


autoRaiseDelay 


AutoRaiseDelay 


milljsec 


500 


bitmapDirectory 


BitmapDirectory 


directory 


/usr/include/Xll/bitmaps 


button Bi ndi ngs 


ButtonBindings 


string 


NULL 


cleanText 


CleanText 


T/F 


T 


clientAutoPlaoe 


ClientAutoPlaoe 


T/F 


T 


colormapFocusPolicy 


ColormapFocusPolicy 


string 


keyboard 


configFUe 


ConfigFile 


file 


.mwmrc 


deiconifyKeyFocus 


DeiconifyKeyFocus 


T/F 


T 


doiftleOickTime 


DoubleClickTirne 


millisec 


500 


enforceKeyFocus 


Enforce KeyFocus 


T/F 


T 


fadeNormallcon 


FadeNormallcon 


T/F 


F 


frame BorderAVidth 


Frame BorderWidth 


pixels 


5 


iconAutoPlace 


IconAutoPlaoe 


T/F 


T 


iconBoxGcome t ry 


IconBoxGeometry 


string 


6x1+0-0 


iconBoxName 


IconBoxNaroe 


string 


ioonbox 


iconBoxTitle 


IconBoxTitle 


string 


Icons 


iconClick 


IconClick 


T/F 


T 


iconDecoration 


IconDecoration 


string 


varies 


icooImageMaxiniurn, 


IconlmageMaxirnurn 




50x50 


iconlroageMinimum 


Iconl mage N^imrouro 




32x32 


iconP lace roe nt 


IconP lace me nt 


string 


left bottom 


iconP lace roe nt Margin 


IconP lace me nt Margin 


pixels 


varies 


interact ivePlace me nt 


Interact ivePlace roe nt 


T/F 


F 


keyBindings 


KeyBindings 


string 


Motif 


keyboardFocusPolicy 


KeyboardFocusPolicy 


string 


explicit 


limitResize 


LimitResize 


T/F 


T 


IcwerOnlconify 


LowerOnlconify 


T/F 


T 


maxinmrnMaxi mutnSizc 


Mayi mnmMavi miifliSfoe 


wxh (pixels) 


2X screen w&h 


moveThreshold 


MoveThreshold 


pixels 


4 


passButtons 


PassButtons 


T/F 


F 


passSelectButton 


PassSelectButton 


T/F 


T 


positionlsFrame 


PositionlsFrame 


T/F 


T 


positionOnScreen 


PositionOnScreen 


T/F 


T 


quitTiroeout 


QuitTimeout 


millisec. 


1000 


resizeBorderWidth. 


ResizeBorderWidth 






resizeCursors 


ResizeCursors 


T/I7 


T 








all 


startupKeyFocus 


StartupKeyFocus 


T/F 


T 


transient Decoration 


Transient Decoration 


string 


system title 


transient Functions 


Transient Functions 


string 


-minimize -maximize 


uselconBax 


UselconBox 


T/F 


F 


wMenuButtonClick 


WMenuButtonOick 


T/F 


T 


wMenuButtonClick2 


WMenuButtonClick2 


T/F 


T 



autoKeyFocus (class AutoKeyFocus) 

This resource is only available when the keyboard input focus policy is explicit. If 
autoKeyFocus is given a value of True, then when a window with the keyboard input 
focus is withdrawn from window management or is iconified, the focus is set to the previ- 
ous window that had the focus. If the value given is False, there is no automatic setting 
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of the keyboard input focus. The default value is True. 

autoRaiseDelay (class AutoRaiseDelay) 

This resource is only available when the focusAutoRaise resource is True and the key- 
board focus policy is pointer. The autoRaiseDelay resource specifies the amount of time 
(in milliseconds) that mwm will wait before raising a window after it gets the keyboard 
focus. The default value of this resource is 500 (ms). 

bitmapDirectory (class BitmapDirectory) 

This resource identifies a directory to be searched for bitmaps referenced by mwm 
resources. This directory is searched if a bitmap is specified without an absolute path- 
name. The default value for this resource is "/usr/include/Xll/bitmaps". 

buttonBindings (class ButtonBindings) 

This resource identifies the set of button bindings for window management functions. 
The named set of button bindings is specified in the mwm resource description file. 
These button bindings are merged with the built-in default bindings. The default value 
for this resource is NULL (i.e., no button bindings are added to the built-in button bind- 
ings). 

cleanText (classCleanText) 

This resource controls the display of window manager text in the client title and feedback 
windows. If the default value of True is used, the text is drawn with a clear (no stipple) 
background. This makes text easier to read on monochrome systems where a back- 
groundPixmap is specified. Only the stippling in the area immediately around the text is 
cleared. If False, the text is drawn directly on top of the existing background. 

clientAutoPIace (class ClientAutoPIace) 

This resource determines the position of a window when the window has not been given 
a user specified position. With a value of True, windows are positioned with the top left 
corners of the frames offset horizontally and vertically. A value of False causes the 
currently configured position of the window to be used. In either case, MWM will 
attempt to place the windows totally on-screen. The default value is True. 

colormapFocusPolicy (class ColormapFocusPolicy) 

This resource indicates the colormap focus policy that is to be used. If the resource 
value is explicit then a colormap selection action is done on a client window to set the 
colormap focus to that window. If the value is pointer then the client window containing 
the pointer has the colormap focus. If the value is keyboard then the client window that 
has the keyboard input focus will have the colormap focus. The default value for this 
resource is keyboard. 

configFile (class ConfigFile) 

The resource value is the pathname for an mwm resource description file. The default is 
.mwmrc in the user's home directory (based on the $HOME environment variable) if 
this file exists, otherwise /usr/lib/Xll/system.mwmrc. 

deiconifyKeyFocus (class DeiconifyKeyFocus) 

This resource only applies when the keyboard input focus policy is explicit. If a value of 
True is used, a window will receive the keyboard input focus when it is normalized 
(deiconified). True is the default value. 

doubleClickTime (class DoubleCIickTime) 

This resource is used to set the maximum time (in ms) between the clicks (button 
presses) that make up a double-click. The default value of this resource is 500 (ms). 

enforceKeyFocus (class EnforceKeyFocus) 

If this resource is given a value of True, then the keyboard input focus is always explicitly 
set to selected windows even if there is an indication that they are "globally active" input 
windows. (An example of a globally active window is a scroll bar that can be operated 
without setting the focus to that client) If the resource is False, the keyboard input focus 
is not explicitly set to globally active windows. The default value is True. 
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fadeNormallcon (class FadeNormallcon) 

If this resource is given a value of True, an icon is grayed out whenever it has been nor- 
malized (its window has been opened). The default value is False. 

frameBorderWidth (class FrameBorderWidth) 

This resource specifies the width (in pixels) of a client window frame border without 
resize handles. The border width includes the 3-D shadows. The default value is 5 pix- 
els. 

iconAutoPlace (class IconAutoPlace) 

This resource indicates whether icons are automatically placed on the screen by mwm, or 
are placed by the user. Users may specify an initial icon position and may move icons 
after initial placement; however, mwm will adjust the user-specified position to fit into an 
invisible grid. When icons are automatically placed, mwm places them into the grid 
using a scheme set with the iconPlacement resource. If the iconAutoPlace resource has a 
value of True, then mwm does automatic icon placement A value of False allows user 
placement The default value of this resource is True. 

iconBoxGeometry (class IconBoxGeometry) 

This resource indicates the initial position and size of the icon box. The value of the 
resource is a standard window geometry string with the following syntax: 

[= \\mdth\height][{ + -}xoffset{ + -}yoffset] 

If the offsets are not provided, the iconPlacement policy is used to determine the initial 
placement. The units for width and height are columns and rows. The actual screen size 
of the icon box window will depend on the iconlmageM aximum (size) and iconDecora- 
tion resources. The default value for size is (6 * iconWidth + padding) wide by (1 * 
iconHeight + padding) high. The default value of the location is +0 -0. 

iconBoxName (class IconBoxName) 

This resource specifies the name that is used to look up icon box resources. The default 
name is iconbox. 

iconBoxTitle (class IconBoxTitle) 

This resource specifies the name that is used in the title area of the icon box frame. The 
default value is Icons. 

iconClick (class IconClick) 

When this resource is given the value of True, the system menu is posted and left posted 
when an icon is clicked. The default value is True. 

iconDecoration (class IconDecoration) 

This resource specifies the general icon decoration. The resource value is label"(only 
the label part is displayed) or image (only the image part is displayed) or label image 
(both the label and image parts are displayed). A value of activelabel can also be 
specified to get a label (not truncated to the width of the icon) when the icon is selected. 
The default icon decoration for icon box icons is that each icon has a label part and an 
image part (label image). The default icon decoration for stand-alone icons is that each 
icon has an active label part, a label part and an image part (activelabel label image). 

iconlmageMaximum (class IconlmageMaxiimim) 

This resource specifies the maximum size of the icon image. The resource value is 
widthxheight (e.g., 64x64). The maximum supported size is 128x128. The default value of 
this resource is 50x50. 

iconlmageMinimum (class IconlmageMinimum) 

This resource specifies the minimum size of the icon image. The resource value is 
widthxheight (e.g., 32x50). The minimum supported size is 16x16. The default value of 
this resource is 32x32. 

iconPlacement (class IconPlacement) 

This resource specifies the icon placement scheme to be used. The resource value has 
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the following syntax: 

primary Jayout secondary Jay out 
The layout values are one of the following: 

top Lay the icons out top to bottom, 

bottom Lay the icons out bottom to top. 

left Lay the icons out left to right 

right Lay the icons out right to left 

A horizontal (vertical) layout value should not be used for both the primary Jayout and 
the secondary Jayout (e.g., don't use top for the primary Jayout and bottom for the 
secondary Jayout). The primary Jayout indicates whether, when an icon placement is 
done, the icon is placed in a row or a column and the direction of placement. The 
secondary Jayout indicates where to place new rows or columns. For example, top right 
indicates that icons should be placed top to bottom on the screen and that columns 
should be added from right to left on the screen. The default placement is left bottom 
(icons are placed left to right on the screen, with the first row on the bottom of the 
screen, and new rows added from the bottom of the screen to the top of the screen). 

iconPlacementMargin (class IconPlacementMargin) 

This resource sets the distance between the edge of the screen and the icons that are 
placed along the edge of the screen. The value should be greater than or equal to 0. A 
default value (see below) is used if the value specified is invalid. The default value for 
this resource is equal to the space between icons as they are placed on the screen (this 
space is based on maximizing the number of icons in each row and column). 

interactivePlacement (class InteractivePlacement) 

This resource controls the initial placement of new windows on the screen. If the value is 
True, then the pointer shape changes before a new window is placed on the screen to 
indicate to the user that a position should be selected for the upper-left hand corner of 
the window. If the value is False, then windows are placed according to the initial win- 
dow configuration attributes. The default value of this resource is False. 

keyBindings (class KeyBindings) 

This resource identifies the set of key bindings for window management functions. If 
specified these key bindings replace the built-in default bindings. The named set of key 
bindings is specified in mwm resource description file. The default value for this resource 
is the set of compatible key bindings. 

keyboardFocusPolicy (class KeyboardFocusPolicy) 

If set to pointer, the keyboard focus policy is to have the keyboard focus set to the client 
window that contains the pointer (the pointer could also be in the client window decora- 
tion that mwm adds). If set to explicit, the policy is to have the keyboard focus set to a 
client window when the user presses button 1 with the pointer on the client window or 
any part of the associated mwm decoration. The default value for this resource is expli- 
cit. 

limitResize (class LimitResize) 

If this resource is True, the user is not allowed to resize a window to greater than the 
maximum size. The default value for this resource is True. 

lowerOnlconify (class LowerOnlconify) 

If this resource is given the default value of True, a window's icon appears on the bottom 
of the window stack when the window is minimized (iconified). A value of False places 
the icon in the stacking order at the same place as its associated window. 

maximumMaximumSize (class MaximumMaximumSize) 

This resource is used to limit the maximum size of a client window as set by the user or 
client. The resource value is widtfrxheight (e.g., 1024x1024) where the width and height 
are in pixels. The default value of this resource is twice the screen width and height. 
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moveThreshoId (class MovcThreshold) 

This resource is used to control the sensitivity of dragging operations that move windows 
and icons. The value of this resource is the number of pixels that the locator will be 
moved with a button down before the move operation is initiated. This is used to 
prevent window/icon movement when a click or double-click is done and there is unin- 
tentional pointer movement with the button down. The default value of this resource is 4 
(pixels). 

passButtons (class PassButtons) 

This resource indicates whether or not button press events are passed to clients after 
they are used to do a window manager function in the client context If the resource 
value is False, then the button press will not be passed to the client If the value is True, 
the button press is passed to the client window. The window manager function is done 
in either case. The default value for this resource is False. 

passSelectButton (class PassSelectButton) 

This resource indicates whether or not the keyboard input focus selection button press 
(if keyboardFocusPolicy is explicit) is passed on to the client window or used to do a win- 
dow management action associated with the window decorations. If the resource value is 
False then the button press will not be used for any operation other than selecting the 
window to be the keyboard input focus; if the value is True, the button press is passed to 
the client window or used to do a window management operation, if appropriate. The 
keyboard input focus selection is done in either case. The default value for this resource 
is True. 

positionlsFrame (class PositionlsFrame) 

This resource indicates how client window position information (from the 
WMNORMALHINTS property and from configuration requests) is to be interpreted. 
If the resource value is True then the information is interpreted as the position of the 
mwm client window frame. If the value is False then it is interpreted as being the posi- 
tion of the client area of the window. The default value of this resource is True. 

positionOnScreen (class PositionOnScreen) 

This resource is used to indicate that windows should initially be placed (if possible) so 
that they are not clipped by the edge of the screen (if the resource value is True). If a 
window is larger then the size of the screen then at least the upper left corner of the win- 
dow will be on-screen. If the resource value is False, then windows are placed in the 
requested position even if totally off-screen. The default value of this resource is True. 

quitTimeout (class QuitTimeout) 

This resource specifies the amount of time (in milliseconds) that mwm will wait for a 
client to update the WM COMMAND property after mwm has sent the 
WMSAVEYOURSELF message. This protocol will only be used for those clients that 
have a WM SAVE YOURSELF atom and no WM DELETE WINDOW atom in the 
WMP ROTOCOLS client window property. The default value~of this resource is 1000 
(ms). (Refer to the f.kill function for additional information.) 

resizeBorderWidth (class ResizeBorderWidth) 

This resource specifies the width (in pixels) of a client window frame border with resize 
handles. The specified border width includes the 3-D shadows. The default is 10 (pix- 
els). 

resizeCursors (class ResizeCursors) 

This is used to indicate whether the resize cursors are always displayed when the pointer 
is in the window size border. If True the cursors are shown, otherwise the window 
manager cursor is shown. The default value is True. 

showFeedback (class ShowFeedback) 

This resource controls when feedback information is displayed. It controls both window 
position and size feedback during move or resize operations and initial client placement 
It also controls window manager message and dialog boxes. The value for this resource 
is a list of names of the feedback options to be enabled; the names must be separated by 
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a space. The names of the feedback options are shown below: 



Name 


Description 


all 


Show all feedback. (Default value.) 


behavior 


Confirm behavior switch. 


move 


Show position during move. 


none 


Show no feedback. 


placement 


Show position and size during initial placement. 


resize 


Show size during resize. 


restart 


Confirm mwm restart. 



The following command line illustrates the syntax for showFeedback: 
Mwm*showFeedbaclc placement resize behavior restart 

This resource specification provides feedback for initial client placement and resize, and 
enables the dialog boxes to confirm the restart and set behavior functions. It disables 
feedback for the move function. 

startupKeyFocus (class StartupKeyFocus) 

This resource is only available when the keyboard input focus policy is explicit. When 
given the default value of True, a window gets the keyboard input focus when the window 
is mapped (i.e., initially managed by the window manager). 

transientDecoration (class TransientDecoration) 

This controls the amount of decoration that Mwm puts on transient windows. The 
decoration specification is exactly the same as for the clientDecoration (client specific) 
resource. Transient windows are identified by the WM TRANSIENT FOR property 
which is added by the client to indicate a relatively temporary window. The default value 
for this resource is menu title (i.e., transient windows will have resize borders and a 
titlebar with a window menu button). 

transientFunctions (class TransientFunctions) 

This resource is used to indicate which window management functions are applicable (or 
not applicable) to transient windows. The function specification is exactly the same as 
for the clientFunctions (client specific) resource. The default value for this resource is 
-minimize -maximize. 

uselconBox (class UselconBox) 

If this resource is given a value of True, icons are placed in an icon box. When an icon 
box is not used, the icons are placed on the root window (default value). 

wMenuButtonClick (class WMenuButtonClick) 

This resource indicates whether a click of the mouse when the pointer is over the win- 
dow menu button will post and leave posted the system menu. If the value given this 
resource is True, then the menu will remain posted. True is the default value for this 
resource. 

wMenuButtonClick2 (class WMenuButtonClick2) 

When this resource is given the default value of True, a double-click action on the win- 
dow menu button will do an f.kill function. 

CLIENT SPECIFIC RESOURCES 

The syntax for specifying client specific resources is 

M\vm*client_name_or_class*resource_id 

For example, Mwm*mterm*windowMenu is used to specify the window menu to be used with 
mterm clients. 
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The syntax for specifying client specific resources for all classes of clients is 
Mwm+resourceid 

Specific client specifications take precedence over the specifications for all clients. For example, 
Mwm*windowMenu is used to specify the window menu to be used for all classes of clients that 
don't have a window menu specified. 

The syntax for specifying resource values for windows that have an unknown name and class (i.e. 
the window does not have a WMCLASS property associated with it) is 

Mwm*defaults*ras0w/ce_«/ 

For example, Mwm*defaults*iconImage is used to specify the icon image to be used for windows 
that have an unknown name and class. 



The following client specific resources can be specified: 



Client Specific Resources 


Name 


Class 


Value Type 


Default 


client Decoration 


Client Decoration 


string 


all 


clientFunctions 


ClientFunctions 


string 


all 


focusAutoRaise 


FocusAutoRaise 


T/F 


T 


iconlmage 


Iconlmage 


pathname 


(image) 


iconlmageBackground 


Background 


color 


icon background 


iconlmageBottomShadowColor 


Foreground 


color 


icon bottom shadow 


iconlmageBottomShadowPixmap 


BottomShadowPixmap 


color 


icon bottom shadow pixmap 


iconlmageForeground 


Foreground 


color 


icon foreground 


iconlmageTopShadowColor 


Background 


color 


icon top shadow color 


iconlmageTopShadowPixmap 


TopShadowPixmap 


color 


icon top shadow pixmap 


matteBackground 


Background 


color 


background 


matteBottomShadowColor 


Foreground 


color 


bottom shadow color 


matteBottomShadowPixmap 


BottomShadowPixmap 


color 


bottom shadow pixmap 


matteForegrovtnd 


Foreground 


color 


foreground 


matteTopShadowColor 


Background 


color 


top shadow color 


matteTopShadowPixmap 


TopShadowPixmap 


color 


top shadow pixmap 


matteWidth 


MatteWidth 


pixels 


0 


maximumClientSize 


MaximumClientSize 


wxh 


fill the screen 


useClientlcon 


UseClientlcon 


T/F 


F 


windowMenu 


WindowMenu 


string 


string 



clientDecoration (class ClientDecoration) 

This resource controls the amount of window frame decoration. The resource is 
specified as a list of decorations to specify their inclusion in the frame. If a decoration is 
preceded by a minus sign, then that decoration is excluded from the frame. The sign of 
the first item in the list determines the initial amount of decoration. If the sign of the 
first decoration is minus, then mwm assumes all decorations are present and starts sub- 
tracting from that set. If the sign of the first decoration is plus (or not specified), then 
mwm starts with no decoration and builds up a list from the resource. 
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Name 


Description 


all 


Include all decorations (default value). 


border 


Window border. 


maximize 


Maximize button (includes title bar). 


minimize 


Minimize button (includes title bar). 


none 


No decorations. 


resized 


Border resize handles (includes border). 


menu 


Window menu button (includes title bar). 


title 


Title bar (includes border). 



Examples: 

Mwm*XClock*cUentDecoration: -resizeh -maximize 

This removes the resize handles and maximize button from X Clock windows. 

Mwm*XClock*clientDecoration: menu minimize border 
This does the same thing as above. Note that either menu or minimize implies title. 

clientFunctions (class ClientFunctions ) 

This resource is used to indicate which MWM functions are applicable (or not applica- 
ble) to the client window. The value for the resource is a list of functions. If the first 
function in the list has a minus sign in front of it, then MWM starts with all functions and 
subtracts from that set. If the first function in the list has a plus sign in front of it, then 
MWM starts with no functions and builds up a list. Each function in the list must be pre- 
ceded by the appropriate plus or minus sign and be separated from the next function by 
a space. 

The table below lists the functions available for this resource: 



Name 


Description 


aU 


Include all functions (default value) 


none 


No functions 


resize 


f.resize 


move 


f.move 


minimize 


tminimize 


maximize 


{.maximize 


close 


{Ml 



focusAutoRaise (class FocusAutoRaise) 

When the value of this resource is True, clients are made completely unobscured when 
they get the keyboard input focus. If the value is False, the stacking of windows on the 
display is not changed when a window gets the keyboard input focus. The default value 
is True. 

iconlmage (class Iconlmage) 

This resource can be used to specify an icon image for a client (e.g., 
w Mwm*myclock*iconImage"). The resource value is a pathname for a bitmap file. The 
value of the (client specific) useClientlcon resource is used to determine whether or not 
user supplied icon images are used instead of client supplied icon images. The default 
value is to display a built-in window manager icon image. 

iconlmageBackground (class Background) 

This resource specifies the background color of the icon image that is displayed in the 
image part of an icon. The default value of this resource is the icon background color 
(i.e., specified by "Mwm 'background or Mwm*icon*background). 
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iconlmageBottomShadowColor (class Foreground) 

This resource specifies the bottom shadow color of the icon image that is displayed in 
the image part of an icon. The default value of this resource is the icon bottom shadow 
color (i.e., specified byMwm'icon'bottomShadowColor). 

iconlmageBottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the icon image that is displayed in 
the image part of an icon. The default value of this resource is the icon bottom shadow 
Pixmap (i.e., specified by Mwm * icon * bottomShadowPixmap) . 

konlmageForeground (class Foreground) 

This resource specifies the foreground color of the icon image that is displayed in the 
image part of an icon. The default value of this resource is the icon foreground color 
(i.e., specified by "Mwm * foreground or Mwm*icon*foreground). 

konlmageTopShadowColor (class Background) 

This resource specifies the top shadow color of the icon image that is displayed in the 
image part of an icon. The default value of this resource is the icon top shadow color 
(i.e., specified by Mwm*icon*topShadowColor). 

konlmageTopShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the icon image that is displayed in the 
image part of an icon. The default value of this resource is the icon top shadow Pixmap 
(i.e., specified by Mwm*icon*topShadowPixmap). 

matteBackground (class Background) 

This resource specifies the background color of the matte, when matteWidth is positive. 
The default value of this resource is the client background color (i.e., specified by 
"Mwm'background or Mwm*client*background). 

matteBottomShadowColor (class Foreground) 

This resource specifies the bottom shadow color of the matte, when matteWidth is posi- 
tive. The default value of this resource is the client bottom shadow color (i.e., specified 
by "Mwm*bottomShadowColor or Mwm*client*bottomShadowColor). 

matteBottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the matte, when matteWidth is 
positive. The default value of this resource is the client bottom shadow Pixmap (i.e., 
specified by "Mwm*bottomShadowPixmap or Mwm*client*bottomShadowPixmap). 

matteForeground (class Foreground) 

This resource specifies the foreground color of the matte, when matteWidth is positive. 
The default value of this resource is the client foreground color (i.e., specified by 
"Mwm * foreground or Mwm*client*foreground). 

matteTopShadowColor (class Background) 

This resource specifies the top shadow color of the matte, when matteWidth is positive. 
The default value of this resource is the client top shadow color (i.e., specified by 
"Mwm*topShadowColor or Mwm*client*topShadowColor). 

matteTopShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the matte, when matteWidth is posi- 
tive. The default value of this resource is the client top shadow Pixmap (i.e., specified by 
"Mwm*topShadowPixmap or Mwm*client*topShadowPixmap). 

matteWidth (class MatteWidth) 

This resource specifies the width of the optional matte. The default value is 0, which 
effectively disables the matte. 

maximumClientSize (class MaximumClientSize) 

This is a size specification that indicates the client size to be used when an application is 
maximized. The resource value is specified as widthxheight. The width and height are 
interpreted in the units that the client uses (e.g., for terminal emulators this is generally 
characters). If this resource is not specified then the maximum size from the 
WM NORMAL HINTS property is used if set Otherwise the default value is the size 
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where the client window with window management borders fills the screen. When the 
maximum client size is not determined by the maximumClientSize resource, the max- 
imumMaximumSize resource value is used as a constraint on the maximum size. 

useClientlcon (class UseClientlcon) 

If the value given for this resource is True, then a client supplied icon image will take 
precedence over a user supplied icon image. The default value is False, making the user 
supplied icon image have higher precedence than the client supplied icon image. 

windowMenu (class WindowMenu) 

This resource indicates the name of the menu pane that is posted when the window 
menu is popped up (usually by pressing button 1 on the window menu button on the 
client window frame). Menu panes are specified in the mwm resource description file 
file. Window menus can be customized on a client class basis by specifying resources of 
the form Mwm*client_name_or_class*wind(mMemj (see the "Mwm Resource Descrip- 
tion File Syntax" section in Ihis man page). The default value of this resource is the 
name of the built-in window menu specification. 

RESOURCE DESCRIPTION FILE 

The mwm resource description file is a supplementary resource file that contains resource descrip- 
tions that are referred to by entries in the defaults files (.Xdefaults, app-defaults/Mwm). It con- 
tains descriptions of resources that are to be used by mwm, and that cannot be easily encoded in 
the defaults files (a bitmap file is an analogous type of resource description file). A particular 
mwm resource description file can be selected using the configFile resource. 

The following types of resources can be described in the mwm resource description file: 

Buttons Window manager functions can be bound (associated) with button events. 

Keys Window manager functions can be bound (associated) with key press events. 

Menus Menu panes can be used for the window menu and other menus posted with key 

bindings and button bindings. 

MWM RESOURCE DESCRIPTION FILE SYNTAX 

The mwm resource description file is a standard text file that contains items of information 
separated by blanks, tabs, and new lines characters. Blank lines are ignored. Items or characters 
can be quoted to avoid special interpretation (e.g., the comment character can be quoted to 
prevent it from being interpreted as the comment character). A quoted item can be contained in 
double quotes ("). Single characters can be quoted by preceding them by the back-slash character 
(\). All text from an unquoted # to the end of the line is regarded as a comment and is not inter- 
preted as part of a resource description. If ! is the first character in a line, the line is regarded as a 
comment. Window manager functions can be accessed with button and key bindings, and with 
window manager menus. Functions are indicated as part of the specifications for button and key 
binding sets, and menu panes. The function specification has the following syntax: 

Junction - function jtame \function_args] 

function name = window manager function 
function~_args - {quoted item \ unquoted item} 

The following functions are supported. If a function is specified that isn't one of the supported 
functions then it is interpreted by mwm as f. nop. 

tbeep This function causes a beep. 

tcircle_down [icon | window] 

"This function causes the window or icon that is on the top of the window stack to 
be put on the bottom of the window stack (so that it is no longer obscuring any 
other window or icon). This function affects only those windows and icons that 
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are obscuring other windows and icons, or that are obscured by other windows 
and icons. Secondary windows (i.e. transient windows) are restocked with their 
associated primary window. Secondary windows always stay on top of the associ- 
ated primary window and there can be no other primary windows between the 
secondary windows and their primary window. If an icon function argument is 
specified, then the function applies only to icons. If a window function argument 
is specified then the function applies only to windows. 

fccircle_up [icon | window] 

"This function raises the window or icon on the bottom of the window stack (so 
that it is not obscured by any other windows). This function affects only those 
windows and icons that are obscuring other windows and icons, or that are 
obscured by other windows and icons. Secondary windows (i.e. transient win- 
dows) are restocked with their associated primary window. If an icon function 
argument is specified then the function applies only to icons. If an window func- 
tion argument is specified then the function applies only to windows. 

fcexec or ! 

This function causes command to be executed (using the value of the SSHELL 
environment variable if it is set, otherwise /bin/sh). The ! notation can be used 
in place of the fcexec function name. 

£focus_color 

~ This function sets the colormap focus to a client window. If this function is done 
in a root context, then the default colormap (setup by the X Window System for 
the screen where mwm is running) is installed and there is no specific client win- 
dow colormap focus. This function is treated as f.nop if colormapFocusPolicy is 
not explicit. 

fcfocus_key 

This function sets the keyboard input focus to a client window or icon. This func- 
tion is treated as f.nop if keyboardFocusPolicy is not explicit or the function is exe- 
cuted in a root context. 

fckill If the WMDELETEWINDOW protocol is set up, the client is sent a client 
message event indicating that the client window should be deleted. If the 
WMSAVEYOURSELF protocol is set up and the WM DELETE WINDOW 
protocol is not set up, the client is sent a client message event indicating that the 
client needs to prepare to be terminated. If the client does not have the 
WM DELETE WINDOW or WM SAVE YOURSELF protocol set up, this 
function causes a client's X connection to be terminated (usually resulting in ter- 
mination of the client). Refer to the description of the quitTimeout resource and 
the WM PROTOCOLS property. 

fclower [client] 

This function lowers a client window to the bottom of the window stock (where it 
obscures no other window). Secondary windows (i.e. transient windows) are res- 
tacked with their associated primary window. The client argument indicates the 
name or class of a client to lower. If the client argument is not specified then the 
context that the function was invoked in indicates the window or icon to lower. 

{.maximize 

This function causes a client window to be displayed with its maximum size. 

fcmenu This function associates a cascading (pull-right) menu with a menu pane entry or 
a menu with a button or key binding. The menujtame function argument 
identifies the menu to be used. 

(minimize 

This function causes a client window to be minimized (iconified). When a win- 
dow is minimized with no icon box in use, and if the lowerOnlconify resource has 
the value True (the default), the icon is placed on the bottom of the window stock 
(such that it obscures no other window). If an icon box is used, then the client's 
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icon changes to its iconified form inside the icon box. Secondary windows (i.e. 
transient windows) are minimized with their associated primary window. There 
is only one icon for a primary window and all its secondary windows. 

tmove This function allows a client window or icon to be moved interactively. 

tnextcmap 

This function installs the next colormap in the list of colormaps for the window 
with the colormap focus. 

tnextkey [icon | window | transient] 

This function sets the keyboard input focus to the next window/icon in the set of 
windows/icons managed by the window manager (the ordering of this set is 
based on the stacking of windows on the screen). This function is treated as f. nop 
if keyboardFocusPoUcy is not explicit The keyboard input focus is only moved to 
windows that do not have an associated secondary window that is application 
modal. If the transient argument is specified, then transient (secondary) win- 
dows are traversed (otherwise, if only window is specified, traversal is done only 
to the last focused window in a transient group). If an icon function argument is 
specified, then the function applies only to icons. If a window function argument 
is specified, then the function applies only to windows. 

tnop This function does nothing. 

f.normaIize 

This function causes a client window to be displayed with its normal size. Secon- 
dary windows (i.e. transient windows) are placed in their normal state along with 
their associated primary window. 

£pack_icons 

This function is used to relayout icons (based on the layout policy being used) on 
the root window or in the icon box. In general this causes icons to be "packed" 
into the icon grid. 

f.pass_keys 

This function is used to enable/disable (toggle) processing of key bindings for 
window manager functions. When it disables key binding processing all keys are 
passed on to the window with the keyboard input focus and no window manager 
functions are invoked. If the / pass Jceys function is invoked with a key binding to 
disable key binding processing the same key binding can be used to enable key 
binding processing. 

f.post_wmenu 

This function is used to post the window menu. If a key is used to post the win- 
dow menu and a window menu button is present, the window menu is automati- 
cally placed with its top-left corner at the bottom-left corner of the window menu 
button for the client window. If no window menu button is present, the window 
menu is placed at the top-left corner of the client window. 

f.prev_cmap 

This function installs the previous colormap in the list of colormaps for the win- 
dow with the colormap focus. 

f.prev_key [icon | window | transient] 

This function sets the keyboard input focus to the previous window/icon in the 
set of windows/icons managed by the window manager (the ordering of this set is 
based on the stacking of windows on the screen). This function is treated as f.nop 
if keyboardFocusPoUcy is not explicit. The keyboard input focus is only moved to 
windows that do not have an associated secondary window that is application 
modal. If the transient argument is specified, then transient (secondary) windows 
are traversed (otherwise, if only window is specified, traversal is done only to the 
last focused window in a transient group). If an icon function argument is 
specified then the function applies only to icons. If an window function argument 
is specified then the function applies only to windows. 
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(quitjnwm 

This function terminates mwm (but NOT the X window system), 
f. raise [-client] 

This function raises a client window to the top of the window stack (where it is 
obscured by no other window). Secondary windows (i.e. transient windows) are 
restacked with their associated primary window. The client argument indicates 
the name or class of a client to raise. If the client argument is not specified then 
the context that the function was invoked in indicates the window or icon to raise. 

f.raise lower 

This function raises a client window to the top of the window stack if it is partially 
obscured by another window, otherwise it lowers the window to the bottom of the 
window stack. Secondary windows (i.e. transient windows) are restacked with 
their associated primary window. 

f.refresh 

This function causes all windows to be redrawn. 
(refresh_win 

This function causes a client window to be redrawn. 

(resize This function allows a client window to be interactively resized, 
(restart 

This function causes mwm to be restarted (effectively terminated and re- 
executed). 

(sendmsg message jiumber 

This function sends a client message of the type MOTIFWMMESSAGES 
with the message Jype indicated by the message jiumber function argument. The 
client message will only be sent if message jtumber is included in the client's 
MOTIF WM MESSAGES property. A menu item label is grayed out if the 
menu item is used to do fsendjnsg of a message that is not included in the 
client's MOTIF WM MESSAGES property. 

(separator 

This function causes a menu separator to be put in the menu pane at the 
specified location (the label is ignored). 

(set behavior 

This function causes the window manager to restart with the default behavior (if a 
custom behavior is configured) or a custom behavior (if a default behavior is 
configured). 

(title This function inserts a title in the menu pane at the specified location. 

Each function may be constrained as to which resource types can specify the function 
(e.g., menu pane) and also what context the function can be used in (e.g., the function is 
done to the selected client window). Function contexts are 

root No client window or icon has been selected as an object for the function. 

window A client window has been selected as an object for the function. This 

includes the window's title bar and frame. Some functions are applied 
only when the window is in its normalized state (e.g., (maximize) or its 
maximized state (e.g., (normalize). 

icon An icon has been selected as an object for the function. 

If a function is specified in a type of resource where it is not supported or is invoked in a 
context that does not apply then the function is treated as f.nop. The following table indi- 
cates the resource types and function contexts in which window manager functions apply. 
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Function 


Contexts 


Resources 


Lbeep 


root,icon,window 


buttonjcey^nenu 


(.circle_down 


rootjcon,window 


buttonJcey,menu 


f.circle_up 


root,icon,window 


buttonJcey,menu 


f.exec 


rootjooivwndow 


buttonjcey.menu 


f.focus_color 


root,icon,window 


buttonJcey,menu 


f.focus_key 


rootJcon,window 


buttonjcey.menu 


(Jcill 


icon,window 


buttonjceyjnenu 


Mower 


root.iconjWindcw 


buttonjcey.menu 


(.maximize 


icon,window(normal) 


buttonJcey,menu 


f.menu 


root ,icon,window 


buttonJcey,menu 


(.minimize 


window 


buttonjceyjnenu 


(.move 


icon,window 


buttonjcey.menu 


(.next_cmap 


root4con,window 


buttonJcey,menu 


tnextjcey 


root,icon,window 


buttonjcey.menu 


f.nop 


root4Con,window 


buttonJcey,menu 


(.normalize 


icon,wirxk^ maximized) 


buttoojteyjnenu 


(.pack_icons 


nx*4con,wtndow 


buttonJcey,menu 


(.pass_keys 


root,icon,window 


buttonjcey.menu 


f.post_wmenu 


root4con,window 


buttonjcey 


f.prev_cmap 


nx*,ic»n,window 


buttonjcey.menu 


f.prevjcey 


root4con,window 


buttonjcey.menu 


Lquit_mwm 


root 


buttonjcey.menu 


(.raise 


root,icon,window 


buttonjcey.menu 


(.raise_lower 


icon,window 


buttonjcey.menu 


(.refresh 


root,icon,window 


buttonjcey .menu 


trefresh_win 


window 


buttonjcey .menu 


(.resize 


window 


buttonJcey,menu 


(.restart 


root 


buttonjcey .menu 


f.send_msg 


icon,window 


buttonjcey .menu 


(separator 


root,ioon,window 


menu 


(jset_behavior 


root4oon,window 


buttonjcey.menu 


(.title 


root,icon,window 


menu 



WINDOW MANAGER EVENT SPECIFICATION 

Events are indicated as part of the specifications for button and key binding sets, and menu panes. 

Button events have the following syntax 

button = [modifierJist]<button_event_name> 
modifier Jist - modifier jiame {modifier name } 

All modifiers specified are interpreted as being exclusive (this means that only the specified 
modifiers can be present when the button event occurs). The following table indicates the values 
that can be used for modifier jiame. The [Alt] key is frequently labeled [Extend] or [Meta]. Alt 
and Meta can be used interchangeably in event specification. 
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Modifier 


Description 


Ctrl 


Control Key 


Shift 


Shift Key 


Alt 


Alt/Meta Key 


Meta 


Meta/Alt Key 


Lock 


Lock Key 


Modi 


Mochfierl 


Mod2 


MocMier2 


Mod3 


Modifier3 


Mod4 


Modified 


ModS 


Modifiers 



The following table indicates the values that can be used for button _event_name. 



Button 


Description 


BtnlDown 


Button 1 Press 


BtnlUp 


Button 1 Release 


Btnl Click 


Button 1 Press and Release 


BtnlClick2 


Button 1 Double Click 


Btn2Down 


Button 2 Press 


Btn2Up 


Button 2 Release 


Btn2Click 


Button 2 Press and Release 


Btn2Click2 


Button 2 Double Click 


Btn3Down 


Button 3 Press 


Btn3Up 


Button 3 Release 


Btn3Click 


Button 3 Press and Release 


Btn3Click2 


Button 3 Double Click 


Btn4Down 


Button 4 Press 


Btn4Up 


Button 4 Release 


Btn4Click 


Button 4 Press and Release 


Btn4Click2 


Button 4 Double Click 


BtnSDown 


Buttons Press 


BtnSUp 


Buttons Release 


BtnSClick 


Button S Press and Release 


Btn5CIick2 


Button S Double Click 



Key events that are used by the window manager for menu mnemonics and for binding to window 
manager functions are single key presses; key releases are ignored. Key events have the following 
syntax: 

key = [modifier Jist\ < Key >key_natne 
modifier Jist = modifier jtctme {modifier jtame} 

All modifiers specified are interpreted as being exclusive (this means that only the specified 
modifiers can be present when the key event occurs). Modifiers for keys are the same as those 
that apply to buttons. The keyjtame is an XI 1 keysym name. Keysym names can be found in the 
keysymdef.h file (remove the XK_ prefix). 

BUTTON BINDINGS 

The buttonBindings resource value is the name of a set of button bindings that are used to 
configure window manager behavior. A window manager function can be done when a button 
press occurs with the pointer over a framed client window, an icon or the root window. The con- 
text for indicating where the button press applies is also the context for invoking the window 
manager function when the button press is done (significant for functions that are context sensi- 
tive). 

The button binding syntax is 



Hewlett-Packard Company 



-22- 



Jul 27, 1989 



mwm(lX) 



mwm(lX) 



Buttons binding set name 
{ 

button context Junction 
button context function 



button context Junction 

} 

The syntax for the context specification is 

context = object[\context] 

object = root | icon | window | title | frame | border | app 

The context specification indicates where the pointer must be for the button binding to be 
effective. For example, a context of window indicates that the pointer must be over a client win- 
dow or window management frame for the button binding to be effective. The frame context is for 
the window management frame around a client window (including the border and titlebar), the 
border context is for the border part of the window management frame (not including the 
titlebar), the title context is for the title area of the window management frame, and the app con- 
text is for the application window (not including the window management frame). 

If an f.nop function is specified for a button binding, the button binding will not be done. 
KEY BINDINGS 

The keyBindings resource value is the name of a set of key bindings that are used to configure 
window manager behavior. A window manager function can be done when a particular key is 
pressed. The context in which the key binding applies is indicated in the key binding specification. 
The valid contexts are the same as those that apply to button bindings. 

The key binding syntax is 

Keys bindings jet jtame 
{ 

key context Junction 
key context Junction 



key context Junction 

} 

If an f.nop function is specified for a key binding, the key binding will not be done. If an 
f.postjvmenu or fmenu function is bound to a key, mwm will automatically use the same key for 
removing the menu from the screen after it has been popped up. 

The context specification syntax is the same as for button bindings. For key bindings, the frame, 
title, border, and app contexts are equivalent to the window context The context for a key event is 
the window or icon that has the keyboard input focus (root if no window or icon has the keyboard 
input focus). 

MENU PANES 

Menus can be popped up using the f.postjvmenu and fmenu window manager functions. The 
context for window manager functions that are done from a menu is root, icon or window depend- 
ing on how the menu was popped up. In the case of the window menu or menus popped up with a 
key binding, the location of the keyboard input focus indicates the context. For menus popped up 
using a button binding, the context of the button binding is the context of the menu. 

The menu pane specification syntax is 
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Menu menujiame 
{ 

label [mnemonic] [accelerator] Junction 
label [mnemonic] [accelerator] Junction 



label [mnemonic] [accelerator] Junction 

} 

Each line in the Menu specification identifies the label for a menu item and the function to be 
done if the menu item is selected. Optionally a menu button mnemonic and a menu button key- 
board accelerator maybe specified. Mnemonics are functional only when the menu is posted and 
keyboard traversal applies. 

The label maybe a string or a bitmap file. The label specification has the following syntax 

label = text \ bitmap Jtle 

bitmap Jile = @file_name 

text = quoted Jtem \ unquoted Jtem 

The string encoding for labels must be compatible with the menu font that is used. Labels are 
greyed out for menu items that do the f.nop function or an invalid function or a function that 
doesn't apply in the current context. 

A mnemonic specification has the following syntax 

mnemonic = _character 

The first matching character in the label is underlined. If there is no matching character in the 
label, no mnemonic is registered with the window manager for that label. Although the character 
must exactly match a character in the label, the mnemonic will not execute if any modifier (such as 
Shift) is pressed with the character key. 

The accelerator specification is a key event specification with the same syntax as is used for key 
bindings to window manager functions. 

ENVIRONMENT 

Mwm uses the environment variable $HOME specifying the user's home directory. 

FILES 

/usr/lib /XI 1 /system.mwmrc 
/usr/lib/Xll/app-defaults/Mwm 
$HOME/.Xdefaults 
$HOME/.mwmrc 

COPYRIGHT 

(c) Copyright 1989 by Open Software Foundation, Inc. 

(c) Copyright 1987, 1988, 1989 by Hewlett-Packard Company 

All rights reserved. 

RELATED INFORMATION 

X(l), VendorShell(3X), and XmInstalUmage(3X). 
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NAME 

ApplicationShell - the ApplicationShell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <X11/Shell.h> 

DESCRIPTION 

ApplicationShell is used as the main top-level window for an application. An application should 
only have more than one ApplicationShell if it implements multiple logical applications. 

Classes 

ApplicationShell inherits behavior and resources from Core, Composite, Shell, WMShell, 
VendorShell, and TopLevelShell. 

The class pointer is applicationShellWidgetClass. 

The class name is ApplicationShell. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



ApplicationShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNargc 


XmCNargc 


inl 


NULL 


CSG 


XmNargv 


XmCNargv 


String* 


NULL 


CSG 



XmNargc 

Specifies the number of arguments given in the XmNargv resource. The function 
Xtlnitialize will set this resource on the shell widget instance it creates by using its 
parameters as the values. 

XmNargv 

Specifies the argument list required by a session manager to restart the application, 
should it be killed. This list should be updated at appropriate points by the applica- 
tion if a new state has been reached which can be directly restarted. The function 
Xtlnitialize will set this resource on the shell widget instance it creates by using its 
parameters as the values. 

Inherited Resources 

ApplicationShell inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 



TopLevelShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNiconic 


XmCIoonic 


Boolean 


False 


CSG 


XmNiconName 


XmCIconName 


String 


NULL 


CSG 
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VendorShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdeleteResponse 


XmCDeleteResponsc 


unsigned char 


XmDESTROY 


CSG 


XmNkeyboardFocusPolicy 


XmCKeyboardFocusPohcy 


unsigned char 


XmEXPLICIT 


CSG 


XmNmwmDecorations 


XmCMwmDecorations 


int 


-1 


CSG 


XmNmwmFunctions 


XmCMwmFunctions 


int 


-1 


CSG 


XmNmwmlnputMode 


XmCMwmlnputMode 


int 


-1 


CSG 


XmNmwmMenu 


XmCMwmMenu 


String 


NULL 


CSG 


XmNshellUnitType 


XmCSheUUnitType 


unsigned char 


XmPDCELS 


CSG 



WMShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-1 


CSG 


XmNiconMask 


XmCIconMask 


Pixmap 


NULL 


CSG 


XmNiconPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWindow 


XmaconWindcw 


Window 


NULL 


CSG 


XmNiconX 


XmCIconX 


int 


-1 


CSG 


XmNiconY 


XmOconY 


int 


-1 


CSG 


XmNinitialState 


XmCInitialState 


int 


1 


CSG 


XmNinput 


XmCInput 


Boolean 


True 


CSG 


XmNmaxAspectX 


XmCMaxAspectX 


int 


-1 


CSG 


XmNmaxAspectY 


XmCMaxAspectY 


int 


-1 


CSG 


XmNmaxHeight 


XmCMaxHeight 


int 


-1 


CSG 


XmNmaxWidth 


XmCMaxWidth 


int 


-1 


CSG 


XmNminAspectX 


XmCMinAspectX 


int 


-1 


CSG 


XmNminAspectY 


XmCMinAspectY 


int 


-1 


CSG 


XmNminHeight 


XmCMinHeight 


int 


-1 


CSG 


XmNminWidth 


XmCMinWidth 


int 


-1 


CSG 


XmNtitle 


XmCTitlc 


char * 


NULL 


CSG 


XmNtransient 


XmCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidthlnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindowGroup 


XmCXWndowGroup 


XID 


None 


CSG 


XmNwmTimeout 


XmCWiriTimeout 


int 


fivesecond 


CSG 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometry 


XmCGeometry 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCallbadc 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPEanEDPDCMAP 


CSG 


XmNborderColor 


XmCBordeiCblor 


Pixel 


Blade 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


SheUColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), Shell(3X), WMShell(3X), VendorShell(3X), and TopLevelShell(3X). 
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NAME 

Composite - the Composite widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Composite widgets are intended to be containers for other widgets and can have an arbitrary 
number of children. Their responsibilities (either implemented directly by the widget class or 
indirectly by Intrinsics functions) include. 

• Overall management of children from creation to destruction. 

• Destruction of descendants when the composite widget is destroyed. 

• Physical arrangement (geometry management) of a displayable subset of managed children. 

• Mapping and unmapping of a subset of the managed children. Instances of composite widgets 
need to specify about the order in which their children are kept. For example, an application 
may want a set of command buttons in some logical order grouped by function, and it may 
want buttons that represent file names to be kept in alphabetical order. 

Classes 

Composite inherits behavior and resources from Core. 
The class pointer is compositeWidgetClass. 
The class name is Composite. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



XmNinsertPosition 

Points to the XtOrderProc function described below. 

The following procedure pointer in a composite widget instance is of type XtOrderProc: 



Cardinal (* XtOrderProc) (widget) 
Widget w, 



w Specifies the widget. 

Composite widgets that allow clients to order their children (usually homogeneous boxes) 
can call their widget instance's insert jposition procedure from the class's insert_child pro- 
cedure to determine where a new child should go in its children array. Thus, a client of a 
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composite class can apply different sorting criteria to widget instances of the class, passing in 
a different insert jxisition procedure when it creates each composite widget instance. 

The return value of the insert_position procedure indicates how many children should go 
before the widget. Returning zero indicates that the widget should go before all other chil- 
dren; returning numchildren indicates that it should go after all other children. The default 
insert __position function returns num_children and can be overridden by a specific composite 
widget's resource list or by the argument list provided when the composite widget is created. 



Inherited Resources 

Composite inherits behavior and resources from the following superclass. For a complete 
description of these resources, refer to the man page for that superclass. 



Core Resource Set 


Name 


Class 


1>pe 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColonnap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallbade 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XflYanslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 
Core(3X). 
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NAME 

Constraint - the Constraint widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Constraint widgets maintain additional state data for each child. For example, client-defined con- 
straints on the child's geometry maybe specified. 

When a constrained composite widget defines constraint resources, all of that widget's children 
inherit all of those resources as their own. These constraint resources are set and read just the 
same as any other resources defined for the child. This resource inheritance extends exactly one 
generation down, which means only the first-generation children of a constrained composite 
widget inherit the parent widget's constraint resources. 

Because constraint resources are defined by the parent widgets and not the children, the child 
widgets never directly use the constraint resource data. Constraint resource date is instead used 
by the parents to attach child-specific data to children. 

If using the Release 2 version, type R2Constraint to get the on-line man page. 
Classes 

Constraint inherits behavior and resources from Composite and Core. 
The class pointer is constraintWidgetClass. 
The class name is Constraint. 

New Resources 

Constraint defines no new resources. 

Inherited Resources 

Constraint inherits behavior and resources from Composite and Core. The following table 
defines a set of widget resources used by the programmer to specify data. The programmer 
can also set the resource values for the inherited classes to set attributes for this widget. To 
reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC 
prefix and use the remaining letters. To specify one of the defined values for a resource in a 
.Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or 
upper case, but include any underscores between words). The codes in the access column 
indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), 
retrieved by using XtGetValues (G), or is not applicable (N/A). 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


lype 


Default 


Access 






Al IJoDSJal It/Da 


NULL 


CSG 


XmNanccitOT^sitive 




Boolc&n 




Q 




XmCBackground 




White 


CSG 




XmCPixmsp 


"ocro&p 


Y ml INWFflETRn PIYMAP 


CSG 


XmNborderCblor 


YmmnrrVrT'nl nr 





Black 


CSG 


XmNbordcrPixffl&p 


XmCPixm&p 




YmT INSPPTIFIFn PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWickh 


D^mion 




CSG 




XmCColormap 


Colormsp 


XtCopyFromP&rent 


CG 


XmNdepth 


XmCDcpth 


int 


XtCopyFromP&rent 


CG 


XmNdestroyCallback. 


XmCCallback 


XtCallbackList 


NULL 


Q 


XmN height 


XmCHeight 


Dimension 


o 


CSG 


XmNirwppcdWhgnManagcd 


XinCMappcdWhcnManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitivc 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X) and Core(3X). 
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NAME 

Core - the Core widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Core is the Xt Intrinsic base class for windowed widgets. 

To add support for windowless widgets, three additional classes have been added above Core in 
the class hierarchy. They are Object, RectObj, and WindowObj. WindowObj is a synonym of 
Core that provides no added functionality but was necessary for implementation reasons. 

If using the Release 2 version, type R2Core to get the on-line man page. 
Classes 

All widgets are built from Core. 
The class pointer is widgetClass. 
The class name is Core. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNacoelerators 


XmCAccelerators 


XtTransIations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNborderColor 


XmCBordeiColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED_PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadc 


XmOCallbade 


XtCaUbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTransIations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



XmNaccelerators 

Specifies a translation table that is bound with its actions in the context of a particu- 
lar widget. The accelerator table can then be installed on some destination widget 
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XmNancestorSensitive 

Specifies whether the immediate parent of the widget will receive input events. Use 
the function XtSetSensitive to change the argument to preserve data integrity (see 
XmNsensitive below). 

XmNbackground 

Specifies the background color fc the widget 

XmNbackgroundPixmap 

Specifies a pixmap for tiling the background. The first tile is placed at the upper 
left-hand corner of the widget's window. 

XmNborderColor 

Specifies the color of the border in a pixel value. 

XmNborderPixmap 

Specifies a pixmap to be used for tiling the border. The first tile is placed at the 
upper left-hand corner of the border. 

XmNborderWidth 

Specifies the width of the border that surrounds the widget's window on all four 
sides. The width is specified in pixels. A width of zero means that no border will 
show. 

XmNcolormap 

Specifies the colormap that will be used for conversions to the type Pixel for this 
widget instance. When changed, previously generated pixel values will not be 
affected, but newly generated values will be in the new colormap. 

XmNdepth 

Specifies the number of bits that can be used for each pixel in the widget's window. 
Applications should not change or set the value of this resource as it is set by the Xt 
Intrinsics when the widget is created. 

XmNdestroyCallback 

Specifies a list of callbacks that is called when the widget is destroyed. 

XmNheight 

Specifies the height of the widget's window in pixels, not including the border area. 

XmNmappedWhenManaged 

Maps the widget (makes visible) as soon as it is both realized and managed, if set to 
True. If set to False, the client is responsible for mapping and unmapping the 
widget If the value is changed from True to False after the widget has been realized 
and managed, the widget is unmapped. 

XmN screen 

Specifies the screen on which a widget instance resides. It is read only, except for 
shells. 

XmNsensitive 

Determines whether a widget will receive input events. If a widget is sensitive, the 
Xt Intrinsics' Event Manager will dispatch to the widget all keyboard, mouse button, 
motion, window enter/leave, and focus events. Insensitive widgets do not receive 
these events. Use the function XtSetSensitive to change the sensitivity argument. 
Using XtSetSensitive ensures that if a parent widget has XmNsensitive set to False, 
the ancestor-sensitive flag of all its children will be appropriately set. 

XmNtranslations 

Points to a translations list. A translations list is a list of events and actions that are 
to be performed when the events occur. 

XmNwidth 

Specifies the width of the widget's window in pixels, not including the border area. 

XmNx 

Specifies the x-coordinate of the widget's upper left-hand corner (excluding the 
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border) in relation to its parent widget 

XmNy 

Specifies the y-coordinate of the widget's upper left-hand corner (excluding the 
border) in relation to its parent widget 

RELATED INFORMATION 
WindowObj(3X). 
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NAME 

Object ~ The Object widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Object is never instantiated. Its sole purpose is as a supporting superclass for other widget classes. 
Classes 

The class pointer is objectClass. 
The class name is Object. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestrcyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmNdestroyCallback 

Specifies a list of callbacks that is called when the gadget is destroyed. 
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NAME 

OverrideShell - the OverrideShell widget class 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/ShelLh> 

DESCRIPTION 

OverrideShell is used for shell windows that completely bypass the window manager, for example, 
PopupMenu shells. 

Classes 

OverrideShell inherits behavior and resources from Core, Composite, and Shell. 
The class pointer is overrideShellWidgetClass. 
The class name is OverrideShell. 

New Resources 

OverrideShell defines no new resources, but overrides the XmNoverrideRedirect and 
XmNsaveUnder resources in the Shell class. 

Inherited Resources 

OverrideShell inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


SnellAncestorSensitive 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CSG 


XmNgeometiy 


XmCGeometry 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


True 


CSG 


XmNpopdosvnCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


True 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBadcground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPEQFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPEOFlED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCXtolormap 


Colormap 


ShellColormap 


CG 


XmNdepth 


XmCDcpth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallbadc 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhe nManaged 


Boolean 


True 


CSG 


XmNscrccn 


XmCScrcen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), and Shell(3X). 
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NAME 

RectObj - The RectObj widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

RectObj is never instantiated. Its sole purpose is as a supporting superclass for other widget 
classes. 

Classes 

RectObj inherits behavior and a resource from Object. 
The class pointer is rectObjClass. 
The class name is RectObj. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



RectObj Resource Set 


Name 


Class 




Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



XmNancestorSensitive 

Specifies whether the immediate parent of the gadget will receive input events. Use 
the function XtSetSensitive if you are changing the argument to preserve data 
integrity (see XmNsensitive below). 

XmNborderWidth 

Specifies the width of the border placed around the RectObj 's rectangular display 
area. 

XmNheight 

Specifies the height of the RectObj's rectangular display area. 
XmNsensitive 

Determines whether a RectObj will receive input events. If a RectObj is sensitive, 
the parent will dispatch to the gadget all keyboard, mouse button, motion, window 
enter/leave, and focus events. Insensitive gadgets do not receive these events. Use 
the function XtSetSensitive to change the sensitivity argument. If a parent widget 
has XmNsensitive set to False, the ancestor-sensitive flag of all its children is 
appropriately set. 
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XmNwidth 

Contains the width of the RectObj's rectangular display area. 

XmNx 

Contains the x-coordinate of the gadget's upper left-hand corner in relation to its 
parent's window. 

XmNy 

Contains the y-coordinate of the gadget's upper left-hand corner in relation to its 
parent's window. 

Inherited Resources 

RectObj inherits behavior and a resource from Object. For a description of this resource, 
refer to the Object man page. 



Object Resource Set 




Access 



XmNdestroyCallback XmCCallback XtCallbackList NULL 



C 



RELATED INFORMATION 
Object(3X). 
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NAME 

Shell - the Shell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <X11/Shell.h> 

DESCRIPTION 

Shell is a top-level widget (with only one managed child) that encapsulates the interaction with the 
window manager. 

Classes 

Shell inherits behavior and resources from Composite and Core. 
The class pointer is shellWidgetCIass. 
The class name is Shell 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometiy 


XmGGeometiy 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdcwnCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpopupCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



XmNallowShellResize 

Specifies that if this resource is False, then the Shell widget instance will return 
XtGeometryNo to all geometry requests from its children. 

XmNcreatePopupChildProc 

Specifies the pointer to a function which is called when the Shell widget instance is 
popped up byXtPopup. 

XmNgeometiy 

Specifies the desired geometry for the widget instance. This resource is only exam- 
ined when the widget instance is unrealized and the number of its managed children 
is changed. It will be used to change the values of the XmNx, XmNy, XmNwidth, 
and XmNheight resources. 

XmNoverrideRedirect 

Specifies this is True if the widget instance is an extremely temporary window which 
should be ignored by the window manager. Applications and users should not nor- 
mally alter this resource. 
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XmNpopdownCallback 

Specifies a list of callbacks that is called when the widget instance is popped down 
byXtPopdown. 

XmNpopupCallback 

Specifies a list of callbacks that is called when the widget instance is popped up by 
XtPopup. 

XmNsaveUnder 

Specifies a True value if it is desirable to save the contents of the screen beneath 
this widget instance, avoiding expose events when the instance is unmapped. This is 
a hint, and an implementation may save contents whenever it desires, including 
always or never. 

Inherited Resources 

Shell inherits behavior and resources from the following superclass. For a complete descrip- 
tion of these resources, refer to the man page for that superclass. 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


SbellAncestorSensitive 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XnaNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNbotderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


ShellColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XniCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X) and Core(3X). 
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NAME 

TopLevelShell - the TopLevelShell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#inchide <Xll/ShelLh> 

DESCRIPTION 

TopLevelShell is used for normal top-level windows such as any additional top-level widgets an 
application needs. 

Classes 

TopLevelShell inherits behavior and resources from Core, Composite, Shell, WMShell, and 
Vendorshell. 

The class pointer is topLevelShellWidgetClass. 
The class name is TopLevelShell. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



TopLevelShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNiconic 


XmCIconic 


Boolean 


False 


CSG 


XmNiconName 


XmCIconName 


String 


NULL 


CSG 



XmNiconic 

Specifies that if this is True when the widget instance is realized, then the widget 
instance will indicate to the window manager that the application wishes to start 
iconic, irrespective of the XtNinitialState resource. This resource is only examined 
by the Intrinsics during a call to XtRealize; it is ignored at all other times. 

XmNiconName 

Specifies the short form of the application name to be displayed by the window 
manager when the application is iconif ied. 



Inherited Resources 

TopLevelShell inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 
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VendorShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdeleteResponse 


XmCDeleteResponse 


unsigned char 


XmDESTROY 


CSG 


XmNkeyboardFocusPolicy 


XmCKeyboardFocusPolicy 


unsigned char 


XmEXPLICIT 


CSG 


XmNrnwmDecorations 


XmCMwmDccorations 


int 


-1 


CSG 


XmNmwmFunctions 


XmCMwmFunctions 


int 


-1 


CSG 


XmNrnwrnlnputMode 


XmCMwmlnputMode 


int 


-1 


CSG 


XmNmwmMenu 


XmCMwmMenu 


String 


NULL 


CSG 


XmNshellUnitType 


XrnCShellUnitType 


unsigned char 


XmPKELS 


CSG 



WMSheU Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-1 


CSG 


XmNiconMask 


XmCIconMask 


Pixmap 


NULL 


CSG 


XmNiconPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWindow 


XmCIconWindcw 


Window 


NULL 


CSG 


XmNiconX 


XmCIconX 


int 


-1 


CSG 


XmNiconY 


XmCIconY 


int 


-1 


CSG 


XmNinitialState 


XmCInitialState 


int 


1 


CSG 


XmN input 


XmCInput 


Boolean 


True 


CSG 


XmNmaxAspectX 


XmCMaxAspectX 


int 


-1 


CSG 


XmNmaxAspectY 


XmCMaxAspectY 


int 


-1 


CSG 


XmNmaxHeight 


XmCMaxHeight 


int 


-1 


CSG 


XmNmaxWidth 


XmCMaxWidth 


int 


-1 


CSG 


XmNminAspectX 


XmCMinAspectX 


int 


-1 


CSG 


XmNminAspectY 


XmCMinAspectY 


int 


-1 


CSG 


XmNminHeight 


XmCMinHeight 


int 


-1 


CSG 


XmNminWidth 


XmCMinWidth 


int 


-1 


CSG 


XmNtitle 


XmCTitle 


char * 


NULL 


CSG 


XmNtransient 


XmCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidthlnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindowGroup 


XrnCWindcwGroup 


XID 


None 


CSG 


XmNwmTimeout 


XmCWmTimeout 


int 


fivesecond 


CSG 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowSheUResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometry 


XmCGeometry 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 




Type 


Default 




XmNaccelerators 


XmCAccclcrators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBadcground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNbrEClrlcL> rlXMAr 


CSG 


XmNborderColor 


XmCBordeiColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Cblormap 


ShellCblormap 


CG 


AmN depth 


XmCDepth 


int 


aneUDeptn 


CG 


XxqN oestroyCJailbacK. 


Amuualioaclt 


xccaubacKList 


NULL 


C 


xmrsiieignt 


AnK^rieignt 


Dimension 


0 


CSG 


XmNmappedWhenMana^ed 


AmL.Ma{j{>cu wiiciiiviiijm^cu 


Boolean 




CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), Shell(3X), VendorShell(3X), and WMSheU(3X). 
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NAME 

TransientShell - the TransientShell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <X11/Shell.h> 

DESCRIPTION 

TransientShell is used for shell windows that can be manipulated by the window manager but are 
not allowed to be iconified separately. For example, Dialog boxes make no sense without their 
associated application. They are iconified by the window manager only if the main application 
shell is iconified. 

Classes 

TransientShell inherits behavior and resources from Core, Composite, Shell, WMShell, and 
VendorShell. 

The class pointer is transientShellWidgetClass. 
The class name is TransientShell. 

New Resources 

TransientShell defines no new resources, but overrides the XmNsaveUnder resource in Shell 
and the XmNtransient resource in WMShell. 

Inherited Resources 

TransientShell inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



VendorShell Resource Set 


Name 


Class 


TJrpe 


Default 


Access 


XmNdeleteResponse 


XmCDeleteResponse 


unsigned char 


XmDESTROY 


CSG 


XmNkeyboardFocusPolicy 


XmCKeyboardFocusPolicy 


unsigned char 


XmEXPLIOT 


CSG 


XmNmwmDecorations 


XmCMwmDecorations 


int 


-1 


CSG 


XmNmwmFunctions 


XmCMwmFunctions 


int 


-1 


CSG 


XmNnwmlnputMode 


XmCMwmlnputMode 


int 


-1 


CSG 


XmNmwmMenu 


XmCMwmMenu 


String 


NULL 


CSG 


XmNsheUUnitiype 


XmCShellUnitType 


unsigned char 


XmPKELS 


CSG 
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WMShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-1 


CSG 


XmNiconMask 


XmCIconMask 


Pixmap 


NULL 


CSG 


XmNiconPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWindow 


XmCIconWindow 


Window 


NULL 


CSG 


XmNiconX 


XtnCIconX 


int 


-1 


CSG 


XmNiconY 


XmCIconY 


int 


-1 


CSG 


XmNinitialState 


XmCInitialState 


int 


1 


CSG 


XmN input 


XmOnput 


Boolean 


True 


CSG 


XmNmaxAspectX 


XmCMaxAspectX 


int 


-1 


CSG 


XmNmaxAspectY 


XmCMaxAspectY 


int 


-1 


CSG 


XmNmaxHeight 


XmCMaxHeight 


int 


-1 


CSG 


XmNmaxWidth 


XmCMaxWidth 


int 


-1 


CSG 


XmNminAspectX 


XmCMinAspectX 


int 


-1 


CSG 


XmNminAspectY 


XmCMinAspcctY 


int 


-1 


CSG 


XmNminHeigbt 


XmCMinHeight 


int 


-1 


CSG 


XmNminWidth 


XmCMinWidth 


int 


-1 


CSG 


XmNtitle 


XmCTitle 


char * 


NULL 


CSG 


XmN transient 


XmCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidthlnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindowGroup 


XmCWindowGroip 


XID 


None 


CSG 


XmNwmTimeout 


XmCWinTimeout 


int 


fivesecond 


CSG 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometry 


XmCGeometry 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCaUback 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 

NULL 


Access 
CSG 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccclerators 


XroCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitivc 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixinap 


XmCPixmap 


Pixmap 


XmUNSPECIHED PDCMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNbordcrPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PDCMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


x 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


ShellColorniap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


c 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWbenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslatioos 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), Shell(3X), VendorShell(3X), and WMShell(3X). 
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NAME 

VendorShell - the VendorShell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <X11/Shell.h> 

DESCRIPTION 

VendorShell is an OSF/Motif widget class used as a supporting superclass for all shell classes that 
are visible to the window manager and that are not override redirect. It contains the resources 
that describe the Mwm-specific look and feel. It also manages the Mwm-specific communication 
needed by all VendorShell subclasses. See the Mwm man page for more information. 

Classes 

VendorShell inherits behavior and resources from Core, Composite, Shell, and WMShell 
classes. 

The class pointer is vendorShellWidgetClass. 
The class name is VendorShell. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGet Values (G), or is not applicable (N/A). 



VendorShell Resource Set 


Name 


Class 


Type 


Default 

XmDESTROY 


Access 
CSG 


XmNdeleteResponse 


XmCDeleteResponse 


unsigned char 


XmNkeyboardFocusPolicy 


XmCKeyboardFocusPolky 


unsigned char 


XmEXPLICIT 


CSG 


XmNmwmDecorations 


XmCMwmDecorat ions 


int 


-1 


CSG 


XmNmwmFunctions 


XmCMwmFunctions 


int 


-1 


CSG 


XmN mwml nput Mode 


XmCMwml nputMode 


int 


-1 


CSG 


XmNmwmMenu 


XmCMwmMenu 


String 


NULL 


CSG 


XmNshellUnitType 


XmCShellUnitType 


unsigned char 


XmPIXELS 


CSG 



XmNkeyboardFocusPolicy 

Determines allocation of keyboard focus within the widget hierarchy rooted at this 
shell. The X keyboard focus must be directed to somewhere in the hierarchy for 
this client-side focus management to take effect. 

XmNdeleteResponse 

Determines what action the shell takes in response to a WM DELETE WINDOW 
message. The setting can be one of three values: XmDESTROY, XmUNMAP, and 
XmDO_NOTHING. The resource is scanned, and the appropriate action is taken, 
after the WM_DELETE_WINDOW callback list (if any) that is registered with the 
Protocol manager has been called. 

XmNmwmDecorations 

Includes the decoration flags (specific decorations to add or remove from the win- 
dow manager frame) for MWM HINTS. 
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XmNmwmFunctions 

Includes the function flags (specific window manager functions to include or exclude 
from the system menu for MWM HINTS. 

XmNmwmlnputMode 

Includes the input mode flag (application modal or system modal input focus con- 
straints) for MWMHINTS. 

XmNmwmMenu 

Specifies the menu items that the OSF/Motif window manager should add to the 
end of the system menu. The contents of the string are a list of items separated by 
\nwith the following format: 

label [mnemonic] [ accelerator] function 

If more than one item is specified, the items should be separated by a newline char- 
acter. 

XmNshellUnitType 

Determines geometric resource interpretation. The following values are allowed: 

• XmPIXELS - all values provided to the widget are treated as normal pixel 
values. 

• XmlOOTH MILLIMETERS - all values provided to the widget are treated as 
1/100 millimeter. 

• XmlOOOTHINCHES - all values provided to the widget are treated as 1/1000 
inch. 

• XmlOOTH POINTS - all values provided to the widget are treated as 1/100 
point. A point is a unit used in text processing applications and is defined as 
1/72 inch. 

• XmlOOTH FONT UNITS - all values provided to the widget are treated as 
1/100-font unit. The value used for the font unit is determined in one of two 
ways: The resource XmNfont can be used in a defaults file or on the command 
line; or, the standard command line options of -fn and -font can be used. The 
font unit value is taken as the QUAD WIDTH property of the font. The func- 
tion XmSetFontUnits allows applications to specify the font unit values. 

Inherited Resources 

VendorShell inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 
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WMSbell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-1 


CSG 


XmNiconMask 


XmdoooMask 


Pixmap 


NULL 


CSG 


XmNioonPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWindow 


XmCIconWindow 


Window 


NULL 


CSG 


XmNicohX 


XmCIconX 


int 


"* 


CSG 


XmNiconY 


XmCIconY 


int 




CSG 


XmNinitialState 


XmCInitialState 


int 


1 


CSG 


XmNinput 


XmCInput 


Boolean 


True 


CSG 


XmNmaxAspectX 


XmCMaxAspectX 


int 


** 


CSG 


XmNmaxAspectY 


XmCMaxAspectY 


int 




CSG 


XmNmaxHeight 


XmCMaxHeigbt 


int 




CSG 


XmNmaxWidth 


XmCMaxWidth 


int 


" X 


CSG 


XmNminAspectX 


XmCMinAspectX 


int 


" X 


CSG 


XmNminAspectY 


XmCMinAspectY 


int 


** 


CSG 


XmNminHeight 


XmCMinHeight 


int 


"* 


CSG 


XmNminWidth 


XmCMinWidth 


int 




CSG 


XmNtitle 


XmCTitle 


char * 


NULL 


CSG 


XmNtransient 


XmCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidthlnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindowGroup 


XinCWindowGroup 


XID 


None 


CSG 


XmNwmTimeout 


XmCWrttTirneout 


int 


fivesecond 


CSG 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometry 


XmCGeometiy 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


IJrpe 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitr/e 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


SbellColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


c 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappcdWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScrccn 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), nwm(lX), ShftlI(3X), WMSheIl(3X), XmActivateProtocol(3X), 
XmActivateWMI^otocol(3X),XinAddProtocolCaUback(3X),XniAddWMProto€olCallback(3X)^ 
XmAddProtocols(3X), XmAddWMProtocols(3X), XmDeactivateProtocol(3X), 
XmDeactivateWMProtocol(3X), XmGetAtomName(3X), XmInternAtom(3X), 
XmIsMotifVVMRuniiing(3X),XmRemoveProtocolCaHback(3X), 

XmRemoveWMProtocolCaHback(3X), XmRemoveProtocols(3X),XmRemoveWMProtocols(3X), 
XmSetProtocolHooks(3X), and XmSetWMProtocolHooks(3X). 
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NAME 

WindowObj - the WindowObj widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

WindowObj is an internal Xt Intrinsic widget class. It is a synonym of Core class that provides no 
added functionality but was necessary for implementation reasons. 



Classes 

WindowObj inherits behavior and resources from Object and RectObj classes. 
The class pointer is windowObjCIass. 
The class name is WindowObj. 



RELATED INFORMATION 

Core(3X), Object(3X), RectObj (3 X). 
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NAME 

WMShell - the WMShell widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <X11/Shell.h> 

DESCRIPTION 

WMShell is a top-level widget that encapsulates the interaction with the window manager. 
Classes 

WMShell inherits behavior and resources from Core, Composite, and Shell classes. 
The class pointer is wmShellWidgetClass. 
The class name is WMShell. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



WMShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-X 


CSG 


XmNiconMask 


XmCIconMask 


Pixmap 


NULL 


CSG 


XmNiconPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWimdow 


XmCIconWlndonr 


Window 


NULL 


CSG 


XmNiconX 


XmCIconX 


int 


-1 


CSG 


XmNiconY 


XmCIconY 


int 


-1 


CSG 


XmNinitialState 


XmCInitialState 


int 


1 


CSG 


XmNinput 


XmCInput 


Boolean 


True 


CSG 


XmNmaxAspectX 


XmCMaxAspectX 


int 


-1 


CSG 


XmNmaxAspcctY 


XmCMaxAspectY 


int 


-1 


CSG 


XmNmaxHeight 


XmCMaxHeighl 


int 


-1 


CSG 


XmNmaxWidth 


XmCMaxWidth 


int 


-1 


CSG 


XmNminAspectX 


XmCMinAspectX 


int 


-1 


CSG 


XmNminAspectY 


XmCMinAspectY 


int 


-1 


CSG 


XmNminHeight 


XmCMinHeight 


int 


-1 


CSG 


XmNminWidth 


XmCMinWidth 


int 


-1 


CSG 


XmNtitle 


XmCTitle 


char * 


NULL 


CSG 


XmNtransient 


XmCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidtblnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindowGroup 


XmCWindowGnnq> 


XID 


None 


CSG 


XmNwirfTimeout 


XmCWmTimeout 


int 


fivesecond 


CSG 



XmNheightlnc 

Specifies allowable height for the widget instance by the window manager if this 
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resource is defined. The sizes are XmNminimumHeight plus an integral multiple of 
XmNheightlnc, subject to the XmNmaximumHeight resource. 

XmNiconMask 

Specifies a bitmap which could be used by the window manager to clip the 
XmNiconPixmap bitmap to make the icon nonrectangular. 

XmNiconPixmap 

Specifies a bitmap which could be used by the window manager as the application's 
icon. 

XmNiconWindow 

Specifies the ID of a window which could be used by the window manager as the 
application's icon. 

XmNiconX 

Specifies a suitable place to put the application's icon; this is a hint to the window 
manager in root window coordinates. Since the window manager controls icon 
placement policy, this maybe ignored. 

XmNiconY 

Specifies a suitable place to put the application's icon; this is a hint to the window 
manager in root window coordinates. Since the window manager controls icon 
placement policy, this maybe ignored. 

XmNinitialState 

Specifies the state in which the application wishes the widget instance to start. It 
must be one of the constants NormalState or IconicState. 

XmN input 

Gives the application's input model for this widget and its descendants. 
XmNntaxAspectX 

Gives the maximum aspect ratio (X/Y) that the application wishes the widget 
instance to have. 

XmNmaxA spectY 

Gives the maximum aspect ratio (X/Y) that the application wishes the widget 
instance to have. 

XmNmaxHeight 

Gives the maximum height that the application wishes the widget instance to have. 
XmNmaxWidth 

Gives the maximum width that the application wishes the widget instance to have. 
XmNminA spectX 

Gives the minimum aspect ratio (X/Y) that the application wishes the widget 
instance to have. 

XmNminA spectY 

Gives the minimum aspect ratio (X/Y) that the application wishes the widget 
instance to have. 

XmNminHeight 

Specifies the minimum height that the application wishes the widget instance to 
have. 

XmNminWidth 

Specifies the minimum width that the application wishes the widget instance to have. 
XmNtitle 

Specifies the application name to be displayed by the window manager. 
XmNtransient 

Specifies a Boolean value that is True if the widget instance is a transient window 
which should be treated more lightly by the window manager. Applications and 
users should not normally alter this resource. 
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XmNwaitForWm 

Specifies that the Intrinsics will wait the length of time given by the XmNwmTimeout 
resource for the window manager to respond to certain actions when True, before 
assuming that there is no window manager present This resource will be altered by 
the Intrinsics as it receives, or fails to receive, responses from the window manager. 

XmNwidthlnc 

Specifies allowable width for the widget instance by the window manager if this 
resource is defined. The sizes are XmNmiiumiimWidth plus an integral multiple of 
XmNwidthlnc, subject to the XmNmaximumWidth resource. 

XmNwindowGroup 

Specifies the ID of a window for which this widget instance is associated; a window 
manager may treat all windows in a group in some way, for example, by always mov- 
ing or iconifying them together. 

If this is set on a Shell widget instance that has no parent but has popup children, 
this resource is set to the same value on all popup children of the widget instance, 
all popup children of these children, and so on. See also the XmNtransient 
resource. 

XmNwmTimeout 

Specifies the length of time that the Intrinsics will wait for the window manager to 
respond to certain actions before assuming that there is no window manager 
present. 

Inherited Resources 

WMShell inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAllowShellResize 


Boolean 


False 


CSG 


XmNcreatePopupChildProc 


XrnCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometiy 


XmCGeometry 


String 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpopupCallback 


XmCCallbadt 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


■type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccclerators 


XmCAocelcrators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Blade 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Cdonnap 


ShellColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), and Shell (3X). 
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NAME 

XmActivateProtocol - a VendorShell function that activates a protocoL 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmActivateProtocol {shell, property, protocol) 
Widget shell; 
Atom property, 
Atom protocol; 

void XmActivateWMProtocol {shell, protocol) 
Widget shell; 
Atom protocol; 

DESCRIPTION 

XmActivateProtocol activates a protocol. It updates the handlers and the property if the shell is 
realized. It is sometimes useful to allow a protocol's state information (callback lists, etc.) to per- 
sist, even though the client may choose to temporarily resign from the interaction. This is sup- 
ported by allowing a protocol to be in one of two states: active or inactive. If the protocol is active 
and the shell is realized, then the property will contain the protocol Atom. If the protocol is inactive, 
the Atom will not be present in the property. 

XmActivateWMProtocol is a convenience interface. It calls XmActivateProtocol with the property 
value set to the atom returned by interning WM PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocol Specifies the protocol Atom (or an int cast to Atom). 

For a complete definition of VendorShell and its associated resources, see VendorShell(3X). 

RELATED INFORMATION 

VendorShell(3X), XmActivateWMProtocol(3X) and XmInternAtom(3X). 
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NAME 

XmActivateWMProtocol - a VendorShell convenience interface that activates a protocol. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmActivateWMProtocol {shell, protocol) 
Widget shell', 
Atom protocol; 

DESCRIPTION 

XmActivateWMProtocol is a convenience interface. It calls XmActivateProtocol with the property 
value set to the atom returned by interning WMPROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocol Specifies the protocol Atom (or an int cast to Atom). 

For a complete definition of VendorShell and its associated resources, see VendorShell(3X). 

RELATED INFORMATION 

VendorShell(3X), XmActivateProtocol(3X), and XmInternAtom(3X). 
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NAME 

XmAddProtocolCallback - a VendorShell function that adds client callbacks for a protocol. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmAddProtocolCallback (shell, property, protocol, callback, closure) 

Widget shell; 

Atom property; 

Atom protocol; 

XtCallbackProc callback; 

caddr_t closure; 

void XmAddWMProtocolCallback (shell, protocol, callback, closure) 

Widget shell; 

Atom protocol; 

XtCallbackProc callback; 

caddr t closure; 



DESCRIPTION 

XmAddProtocolCallback adds client callbacks for a protocol. It checks if the protocol is 
registered, and if it is not, calls XmAddProtocols. It then adds the callback to the internal list. 
These callbacks will be called when the corresponding client message is received. 

XmAddWMProtocolCallback is a convenience interface. It calls XmAddProtocolCallback with the 
property value set to the atom returned by interning WM PROTOCOLS. 



shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocol Specifies the protocol Atom (or an int cast to Atom). 

callback Specifies the procedure to call when a protocol message is received. 

closure Specifies the client data to be passed to the callback when it is invoked. 



For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 



RELATED INFORMATION 

VendorSheU(3X), XmAddProtocols(3X), XmAddWMProtocolCaIlback(3X), and 
XmInternAtom(3X) . 
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NAME 

XmAddProtocols - a VendorShell (unction that adds the protocols to the protocol manager and 
allocates the internal tables. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmAddProtocols {shell, property, protocols, num ^protocols) 

Widget shell; 

Atom property; 

Atom * protocols; 

Cardinal num _protocols; 

void XmAddWMProtocols (shell, protocols, num protocols) 
Widget shell; 
Atom * protocols; 

Cardinal num _protocols; 

DESCRIPTION 

XmAddProtocols adds the protocols to the protocol manager and allocates the internal tables. 

XmAddWMProtocols is a convenience interface. It calls XmAddProtocols with the property value 
set to the atom returned by interning WM PROTOCOLS. 



shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocols Specifies the protocol Atoms (or ints cast to Atom). 

num protocols Specifies the number of elements in protocols. 



For a complete definition of VendorShell and its associated resources, see VendorSheIl(3X). 

RELATED INFORMATION 

VendorSheU(3X), XmAddWMProtocols(3X), and XmInternAtom(3X). 
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NAME 

XmAddTabGroup - a function that adds a Manager or a Primitive widget to the list of tab 
groups. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmAddTabGroup (tab jjroup) 

Widget tab jpoup; 

DESCRIPTION 

AddTabGroup adds a Manager or Primitive widget to the list of tab groups associated with a par- 
ticular widget hierarchy. Each instance of the List widget, each multiline Text edit widget, each 
OptionMenu widget, and each ScrollBar widget must be placed within their own tab group; do not 
place other widgets in these groups. This allows the arrow keys to function in their normal 
fashion within these widgets. 

When using the keyboard to traverse through a widget hierarchy, Primitive or Manager widgets 
are grouped together into what are known as tab groups. Any Manager or Primitive widget can 
be a tab group. Within a tab group, move the focus to the next widget within the tab group by 
using the arrow keys. To move to another tab group, enter either the Tab, <Shift>Tab, or 
Key<F6>. 

tab jpvup Specifies the Manager or Primitive widget ID. 

RELATED INFORMATION 

XmManager(3X), XmPrimitive(3X) and XmRemoveTabGroup(3X). 
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NAME 

XmAddWMProtocolCallback - a VendorShell convenience interface that adds client callbacks for 
a protocol. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmAddWMProtocolCallback (shell, protocol, callback, closure) 
Widget shell; 
Atom protocol; 
XtCallbackProc callback; 
caddr_t closure; 

DESCRIPTION 

XmAddWMProtocolCallback is a convenience interface. It calls XmAddProtocolCallback with the 
property value set to the atom returned by interning WM_PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocol Specifies the protocol Atom (or an int cast to Atom). 

callback Specifies the procedure to call when a protocol message is received. 

closure Specifies the client data to be passed to the callback when it is invoked. 

For a complete definition of VendorShell and its associated resources, see VendorShelI(3X). 

RELATED INFORMATION 

VendorShell(3X), XmAddProtocolCallback(3X), XmInternAtom(3X). 
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NAME 

XmAddWMProtocols - a VendorShell convenience interface that adds the protocols to the proto- 
col manager and allocates the internal tables. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmAddWMProtocols {shell, protocols, man ^protocols) 
Widget shell; 
Atom * protocols'. 

Cardinal num protocols; 

DESCRIPTION 

XmAddWMProtocols is a convenience interface. It calls XmAddProtocols with the property value 
set to the atom returned by interning WM_PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocols Specifies the protocol Atoms (or ints cast to Atom). 

num protocols Specifies the number of elements in protocols. 

For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShell(3X), XmAddProtocols(3X), and XmInternAtom(3X). 
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NAME 

XmArrowButton - the ArrowButton widget class. 

SYNOPSIS 

#include <Xm/ArrowB.h> 

DESCRIPTION 

ArrowButton consists of a directional arrow surrounded by a border shadow. When it is selected, 
the shadow moves to give the appearance that the ArrowButton has been pressed in. When the 
ArrowButton is unselected, the shadow moves to give the appearance that the ArrowButton is 
released, or out. 

Classes 

ArrowButton inherits behavior and resources from Core and XmPrimitive classes. 
The class pointer is xmArrowButtonWidgetClass. 
The class name is XmArrowButton. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmArrowButton Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNactivateCallback 


XmCCallbadt 


XtCallbadcList 


NULL 


C 


XmNarmCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNarrowDirection 


XmCArrowDirection 


unsigned char 


XmARROW UP 


CSG 


XmNdisarmCallback 


XmCCallbadc 


XtCallbadcList 


NULL 


C 



XmNactivateCallback 

Specifies a list of callbacks that is called when the ArrowButton is activated. To 
activate the button, press and release mouse button 1 while the pointer is inside the 
ArrowButton widget. Activating the ArrowButton also disarms it. The reason sent 
by this callback is XmCR_ACTIVATE. 

XmNarmCallback 

Specifies a list of callbacks that is called when the ArrowButton is armed. To arm 
this widget, press mouse button 1 while the pointer is inside the ArrowButton. For 
this callback the reason is XmCR_ARM. 

XmNarrowDirection 

Sets the arrow direction. The following are values for this resource: 

• XmARROW UP. 

• XmARROW DOWN. 

• XmARROW LEFT. 

• XmARROW RIGHT. 

XmNdisarmCallback 

Specifies a list of callbacks that is called when the ArrowButton is disarmed. To 
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disarm this widget, press and release mouse button 1 while the pointer is inside the 
ArrowButton. The reason for this callback is XmCR DISARM. 



Inherited Resources 

ArrowButton inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadcwColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadcrarPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNforegrouDd 


XirO'breground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XnrfXallback 


XtCallbadcList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEiiter 


Boolean 


False 


CSG 


XniNhighlightPixmap 


XmCHighlighlPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThickness 


XmCHighlightThickness 


short 


0 


CSG 


XmNshadcwThidcness 


XmCShadonTbickasss 


short 


2 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED_PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPrXELS 


CSG 


XmNuserData 


XmCUserData 


caddr_t 


NULL 


CSG 




Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbadcground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XinNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event; 
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} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. This event will be NULL 

for the XmNactivateCallback if the callback was triggered when Primitive's 
resource XmNtraversalOn was True or if the callback was accessed through 
the ArmAndActivate action routine. 

Behavior 

<BtnlDown>: 

This action causes the arrow to be armed, and the shadow to be drawn in the 
selected state. The callbacks for XmNarmCallback are called. 

<BtnlUp>: 

If the mouse button release occurs when the pointer is within the ArrowButton, 
then the arrow shadows are redrawn in the unselected state. The callbacks for 
XmNactivateCallback are called, followed by callbacks for XmNdisarmCallback. 

If the mouse button release occurs when the pointer is outside the ArrowButton, 
the callbacks for XmNdisarmCallback are called. 

< Leave Window > : 

If the mouse button is pressed and the cursor leaves the widget's window, the arrow 
shadow will be redrawn in its unselected state. 

< Enter Window >: 

If the mouse button is pressed and the cursor leaves and re-enters the widget's win- 
dow, the arrow shadow will be drawn in the same manner as when the button was 
first armed 

Default Translations 

<BtnlDown>: 
<BtnlUp>: 

<Key>Return: 

< Key > Space: 
<EnterWindow>: 

< LeaveWindow > : 

Keyboard Traversal 

For information on keyboard traversal, see the man page for XmPrimitive(3X) and its sec- 
tions on behavior and default translations. 

RELATED INFORMATION 

Core(3X), XmCreateArrowButton(3X), and XmPrimitive(3X). 



Arm() 

Activate() 

Disarm() 

ArmAndActivateO 

ArmAndActivateO 

Enter() 

LeaveQ 
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NAME 

XmArrowButtonGadget - the ArrowButtonGadget widget class. 

SYNOPSIS 

#include <Xm/ArrowBG.h> 

DESCRIPTION 

ArrowButtonGadget consists of a directional arrow surrounded by a border shadow. When it is 
selected, the shadow moves to give the appearance that the ArrowButtonGadget has been pressed 
in. When it is unselected, the shadow moves to give the appearance that the button is released, or 
out. 

Classes 

ArrowButtonGadget inherits behavior and resources from Object, RectObj, and XmGadget 
classes. 

The class pointer is xmArrowButtonGadgetClass. 
The class name is XmArrowButtonGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



ArrowButtonGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNactivateCallback. 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNarrcwDirection 


XmCArrcwDirection 


int 


XmARROW UP 


CSG 


XmNdisarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmNactivateCallback 

Specifies a list of callbacks that is called when the ArrowButtonGadget is activated. 
To activate the button, press and release mouse button 1 while the pointer is inside 
the ArrowButtonGadget. Activating the ArrowButtonGadget also disarms it. The 
reason sent by this callback is XmCR_ACTIVATE. 

XmNarmCallback 

Specifies a list of callbacks that is called when the ArrowButtonGadget is armed. 
To arm this widget, press mouse button 1 while the pointer is inside the ArrowBut- 
tonGadget. For this callback the reason is XmCR_ARM. 

XmNarrowDirection 

Sets the arrow direction. The values for this resource are: 

• XmARROW UP. 

• XmARRO WDOWN . 

• XmARROW LEFT. 

• XmARROW RIGHT. 
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XmNdisarmCallback 

Specifies a list of callbacks that is called when the ArrowButtonGadget is disarmed. 
To disarm this widget, press and release mouse button one while the pointer is 
inside the ArrowButtonGadget. For this callback the reason is XmCR_DISARM. 

Inherited Resources 

ArrowButtonGadget inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 



XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhdpCaUbadc 


XmCCaltoack 


XtCallbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightThickness 


XmCHighlightThidcness 


short 


0 


CSG 


XmNshadowThickness 


XmCShadoWThickness 


short 


2 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPrXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



RectObj Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNheigbt 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. This event will be NULL 

for the XmNactivateCallback if the callback was triggered when Primitive's 
resource XmNtraversalOn was True or if the callback was accessed through 
the ArmAndActivate action routine. 

Behavior 

<BtnlDown>: 

This action causes the arrow to be armed, and the shadow to be drawn in the 
selected state. The callbacks for XmNarmCallback are called. 
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<BtnlUp>: 

If the mouse button release occurs when the pointer is within the ArrowBut- 
tonGadget, then the arrow shadows are redrawn in the unselected state. The call- 
backs for XmNactivateCallback are called, followed by callbacks for XmNdisarm- 
Callback. 

If the mouse button release occurs when the pointer is outside the ArrowBut- 
tonGadget, the callbacks for XmNdisarmCallback are called. 

< Leave Window > : 

If the mouse button is pressed and the cursor leaves the widget's window, the arrow 
shadow will be redrawn in its unselected state. 

< Enter Window >: 

If the mouse button is pressed and the cursor leaves and re-enters the widget's win- 
dow, the arrow shadow will be drawn in the same manner as when the button was 
first armed. 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmGadget(3X) and its sections 
on behavior and default translations. 



RELATED INFORMATION 

Object(3X), RectObj(3X), XmCreateArrowButtonGadget(3X), and XmGadget(3X). 
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NAME 

XmBulktinBoard - the BulIetinBoard widget class. 

SYNOPSIS 

#include <Xm/BulletinB.h> 

DESCRIPTION 

BulIetinBoard is a composite widget that provides simple geometry management for children 
widgets. It does not force positioning on its children, but can be set to reject geometry requests 
that would result in overlapping children. BulIetinBoard is the base widget for most dialog widg- 
ets and is also used as a general container widget 

Modal and modeless dialogs are implemented as collections of widgets that include a DialogShell, 
a BulIetinBoard (or subclass) child of the shell, and various dialog components (buttons, labels, 
etc.) that are children of BulIetinBoard. BulIetinBoard defines callbacks useful for dialogs (focus, 
map, unmap), which are available for application use. If its parent is a DialogShell, BulIetinBoard 
will pass title and input mode (based on dialog style) information to the parent, which is responsi- 
ble for appropriate communication with the window manager. 

Classes 

BulIetinBoard inherits behavior and resources from Core, Composite, Constraint, and 
XmManager classes. 

The class pointer is xmBulletinBoardWidgetClass. 
The class name is XmBuIletinBoard. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmBulletin Board Resource Set 


Name 


Class 


Type 


Default 


Access 




XrnCAllowOverlap 




True 


CSG 


XmNautoUnmanage 







True 


CSG 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


CSG 


XmNcancelButton 


XmCWidget 


Widget 


NULL 


SG 


XmNdefaultButton 


XmCWidget 


Widget 


NULL 


SG 


XmNdefaultPosition 


XmCDefaultPosition 


Boolean 


True 


CSG 


XmNdialogStyle 


XmCDialogStyle 


unsigned cb&r 


dynamic 


CSG 


XmNdialogTitle 


XmCXmString 


XmString 


NULL 


CSG 


XmNfocusCallback 


XmCCallback. 


XtCallbadcList 


NULL 


c 


XmNlabelFontList 


XmCLabelFontList 


XmFontList 


NULL 


CSG 


XmNinapCallback 


XmCCallback 


XtCallbadcList 


NULL 


c 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


CSG 


XmNm&rginV^idth 


XmCMarginV/idth 




10 


CSG 


XmNnoResize 


XmCNoResize 


Boolean 


False 


CSG 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZEANY 


CSG 


XmNshadowType 


XmCShadcwTypc 


unsigned char 


XmSHADOWOUT 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRINGDIRECTIONLTOR 


CSG 


XmNtextFontList 


XmCTextFontList 


XmFontList 


NULL 


CSG 


XmNtextTranslations 


XmCTranslations 


XtTranslations 


NULL 


C 


XmNunmapCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 



XmNallowOverlap 

Controls the policy for overlapping children widgets. If True, BulletinBoard allows 
geometry requests that result in overlapping children. 

XmNautoUnmanage 

Controls whether or not BulletinBoard is automatically unmanaged after a button is 
activated. If True, BulletinBoard adds a callback to button children (PushButtons, 
PushButtonGadgets, and DrawnButtons) that unmanages the BulletinBoard when a 
button is activated; and, the unmap callbacks are called if the parent of the Bulletin- 
Board is a DialogShell. If False, the BulletinBoard is not automatically unmanaged. 

XmNbuttonFontList 

Specifies the font list used for BulletinBoard's button children (PushButtons, Push- 
ButtonGadgets, ToggleButtons, and ToggleButtonGadgets). If NULL, the 
XmNtextFontList is used for buttons. 

XmNcancelButton 

Specifies the widget ID of the Cancel button. BulletinBoard's subclasses, which 
define a Cancel button, set this resource. BulletinBoard does not directly provide 
any behavior for that button. 

XmNdefaultButton 

Specifies the widget ID of the default button. BulletinBoard's subclasses, which 
define a default button, set this resource. BulletinBoard defines translations and 
installs accelerators that activate that button when the return key is pressed. 

XmNdefaultPosition 

Controls whether or not the BulletinBoard is automatically positioned by its parent. 
If True, and the parent of the Bulletinboard is a DialogShell, then the BulletinBoard 
is centered within or around the parent of the DialogShell when the BulletinBoard 
is mapped and managed. If False, the Bulletinboard is not automatically positioned. 

XmNdialogStyle 

Indicates the dialog style associated with BulletinBoard. If the parent of Bulletin- 
Board is a DialogShell, then the parent is configured according to this resource and 
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DialogShell sets the XmNinputMode of VendorShell accordingly. Possible values for 
this resource include the following: 

• XmDIALOGSYSTEMMODAL - used for dialogs that must be responded to 
before any other interaction in any application. 

• XmDIALOGAPPLICATIONMODAL - used for dialogs that must be 
responded to before some other interactions in the same application. 

• XmDIALOG_MODELESS - used for dialogs that do not interrupt interaction 
of any application. 

• XmDIALOG_WORK_AREA - used for non-dialog BulletinBoard widgets 
(parent is noFa subclass of DialogShell). 

XmNdialogTitle 

Specifies the dialog title. If this resource is not NULL, and the parent of the Bul- 
letinBoard is a subclass of WMShell, BulletinBoard sets the XmNtitle of its parent 
to the value of this resource. 

XmNfocusCallback 

Specifies the list of callbacks that is called when the BulletinBoard widget or one of 
its descendants accepts the input focus. The callback reason is XmCR_FOCUS. 

XmNlabelFontList 

Specifies the font list used for BulletinBoard's Label children (Labels and Label- 
Gadgets). If NULL, XmNtextFontList is used for labels also. 

XmNmapCallback 

Specifies the list of callbacks that is called only when the parent of the Bulletin- 
Board is a DialogShell; in which case, this callback list is invoked when the Bulletin- 
Board widget is mapped. The callback reason is XmCR_MAP. 

XmNmarginHeight 

Specifies the minimum spacing in pixels between the top or bottom edge of Bul- 
letinBoard and any child widget. 

XmNmarginWidth 

Specifies the minimum spacing in pixels between the left or right edge of Bulletin- 
Board and any child widget. 

XmNnoResize 

Controls whether or not resize controls are included in the window manager frame 
around the dialog. If set to True, the OSF/Motif window manager does not include 
resize controls in the window manager frame containing the DialogShell or TopLev- 
elShell parent of the BulletinBoard. If set to False, the window manager frame does 
include resize controls. The preferred way to manipulate the set of controls pro- 
vided by the OSF/Motif window manager is to specify values for the mwm resources 
provided by VendorShell. 

XmNresizePolicy 

Controls the policy for resizing BulletinBoard widgets. Possible values include the 
following: 

• XmRESIZENONE - fixed size. 

• XmRESIZE ANY - shrink or grow as needed. 

• XmRESIZE GROW - grow only. 
XmNshadowType 

Describes the shadow drawing style for BulletinBoard. This resource can have the 
following values: 

• XmSHADOW IN - draws the BulletinBoard shadow such that it appears inset. 
This means that the bottom shadow visuals and top shadow visuals are reversed. 

• XmSHADOWOUT - draws the BulletinBoard shadow such that it appears 
outset. 
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• XmSHADOWETCHEDIN - draws the BulletinBoard shadow using a double 
line giving the effect of a line etched into the window, similar to the Separator 
widget 

• XmSHADOW ETCHED OUT - draws the BulletinBoard shadow using a dou- 
ble line giving the effecF of a line coming out of the window, similar to the 
Separator widget 

BulletinBoard widgets draw shadows just within their borders if XmNshadowThick- 
ness is greater than zero. If the parent of a BulletinBoard widget is a DialogShell, 
BulletinBoard dynamically changes the default for XmNshadowThickness from 0 to 
1. 

XmNstringDirection 

Specifies the initial rendering direction for text within a dialog. BulletinBoard's 
subclasses, such as MessageBox and SelectionBox, which create XmString com- 
ponents, such as LabelGadgets, PushButtonGadgets, and Lists, set XmNstringDirec- 
tion of these components based on the value of this resource. BulletinBoard does 
not directly provide any behavior for this resource. 

XmNtextFontList 

Specifies the font list used for BulletinBoard's Text children. If there is no 
XmNbuttonFontList, then this resource is used for buttons; and, if there is no 
XmNIabelFontList, then this resource is used for labels also. 

XmNtextTranslations 

Adds translations to any Text widget or Text widget subclass that is added as a child 
of BulletinBoard. 

XmNunmapCallback 

Specifies the list of callbacks that is called only when the parent of the Bulletin- 
Board is a DialogShell; in which case, this callback list is invoked when the Bulletin- 
Board widget is unmapped. The callback reason is XmCR UNMAP. 

Inherited Resources 

BulletinBoard inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadcwColor 


XaaCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback. 


XtCaUbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XrjoNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadowThickness 


XmCShadooThickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XrnCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmN insertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XrnNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgrouodPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderWIdth 


XmCBoixJerWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCCotormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XrnNdestioyCallback. 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

Behavior 

BulletinBoard behavior is summarized below. 

< Cancel Button Activated > : 

When the Cancel button is pressed, the activate callbacks of the Cancel button are 
called. 

< Default Button Activated > or < Key > Return- 

When the default button or return key is pressed, the activate callbacks of the 
default button are called. 

< Help Button Activated > or <Key>Fl: 

When the Help button or Function key 1 is pressed, the callbacks for XmNhelpCall- 
back are called. 

<FocusIn>: 

When a Focusln event is generated on the widget window, the callbacks for 
XmNfocusCallback are called. 

< MapWindow > : 

When a BulletinBoard, which is the child of a DialogShell, is mapped, the callbacks 
for XmNmapCallback are invoked. When a BulletinBoard that is not the child of a 
DialogShell is mapped, the callbacks are not invoked. 
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< UnmapWindow > : 

When a BulletinBoard that is the child of a DialogShell is unmapped, the callbacks 
for XmNunmapCallback are invoked. When a BulletinBoard that is not the child of 
a DialogShell is unmapped, the callbacks are not invoked. 



Default Translations 

The following are the default translations defined for BulletinBoard widgets: 



<EnterWindow>: Enter() 

<FocusIn>: FocusIn() 

<BtnlDown>: Arm() 

<BtnlUp>: Activate() 

<Key>Fl: Help() 

< Key > Return: Return() 

<Key>KP Enten ReturnQ 



Default Accelerators 

The following are the default accelerator translations that are added to descendants of a 
BulletinBoard if the parent of the BulletinBoard is a DialogShell: 



#override 

<Key>Fl: Help() 

< Key > Return: Retum() 

<Key>KP_Enten ReturnQ 



Keyboard Traversal 

By default, if the parent of a BulletinBoard widget is a DialogShell, BulletinBoard uses the 
Return key for activating the default button and installs accelerators on all descendant widg- 
ets to make this possible. These accelerators disable the normal keyboard traversal 
behavior of the Return key. This traversal behavior may be restored (and the default button 
behavior disabled) by replacing BulletinBoard's default accelerators with an alternative set 
of translations which do not specify the Return action. For more information on keyboard 
traversal, see the man page for XmManager(3X) and its sections on behavior and default 
translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateBulletinBoard(3X), 
XmCreateBuUetinBoardDiaIog(3X), XmDialogSheU(3X), and XmManager(3X). 
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NAME 

XmCascadeButton - the CascadeButton widget class. 

SYNOPSIS 

#include <Xm/CascadeB.h> 

DESCRIPTION 

CascadeButton links two MenuPanes or a MenuBar to a MenuPane. 

It is used in menu systems and must have a RowColumn parent with its XmNrowCoIumnType 
resource set to XmMENU BAR, XmMENU POPUP or XmMENU PULLDOWN. 

It is the only widget that may have a Pulldown MenuPane attached to it as a submenu. The sub- 
menu is displayed when this widget is activated within a MenuBar, a PopupMenu, or a Pulldown- 
Menu. Its visuals can include a label or pixmap and a cascading indicator when it is in a Popop or 
Pulldown MenuPane; or, it can include only a label or a pixmap when it is in a MenuBar. 

The default behavior associated with a CascadeButton depends on the type of menu system in 
which it resides. By default, mouse button 1 controls the behavior of die CascadeButton if it 
resides in a PulldownMenu or a MenuBar; and, mouse button 3 controls the behavior of the Cas- 
cadeButton if it resides in a PopupMenu. The actual mouse button used is determined by its 
RowColumn parent. 

A CascadeButton's visuals differ from most other button gadgets. When the button becomes 
armed, its visuals change from a 2-D to a 3-D look, and it displays the submenu that has been 
attached to it. If no submenu is attached, then it simply changes its visuals. 

When a CascadeButton within a Pulldown or Popup MenuPane is armed as the result of the user 
moving the mouse pointer into the widget, it does not immediately display its submenu. Instead, it 
waits a short amount of time to see if the arming was temporary (i.e., the user was simply passing 
through the widget), or whether the user really wanted the submenu posted. This time delay is 
configurable via XmNmappingDelay. 

CascadeButton provides a single mechanism for activating the widget from the keyboard. This 
mechanism is referred to as a keyboard mnemonic. If a mnemonic has been specified for the 
widget, the user may activate the CascadeButton by simply typing the mnemonic while the Cas- 
cadeButton is visible. If the CascadeButton is in a MenuBar, the meta key must be pressed with 
the mnemonic. Mnemonics are typically used to interact with a menu via the keyboard interface. 

If in a Pulldown or Popup MenuPane and there is a submenu attached, the XmNmarginBottom, 
XmNmarginRight, and XmNmarginTop resources enlarge to accommodate XmNcascaadePixmap. 
XmNmarginWidth defaults to six if this resource is in a MenuBar, otherwise, it takes Label's 
default, which is two. 

Classes 

CascadeButton inherits behavior and resources from Core, XmPrimitive, and XmLabel 
classes. 

The class pointer is xmCascadeButtonWidgetClass. 
The class name is XmCascadeButton. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmCascadeButton Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNcascadePixmap 


XmCPixmap 


Pixmap 


"menu-cascade" 


CSG 


XmNcascadtngCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmappingDelay 


XmCMappingDelay 


int 


100 


CSG 


XmNsubMenuId 


XmCMenuWidget 


Widget 


0 


CSG 



XmNactivateCallback 

Specifies the list of callbacks that is called when the user activates the CascadeBut- 
ton widget, and there is no submenu attached to pop up. The activation occurs by 
releasing a mouse button or by typing the mnemonic associated with the widget. 
The specific mouse button depends on information in the RowColumn parent. The 
reason sent by the callback is XmCR_ACTTVATE. 

XmNcascadePixmap 

Specifies the cascade pixmap displayed on the right end of the widget when a Cas- 
cadeButton is used within a Popup or Pulldown MenuPane and a submenu is 
attached,/ The Label class resources XmNmarginRight , XmNmarginTop, and 
XmNmarginBottom may be modified to ensure room is left for the cascade pixmap. 
The default cascade pixmap is an arrow pointing to the right. 

XniNcascadingCallback 

Specifies the list of callbacks that is called just prior to the mapping of the submenu 
associated with CascadeButton. The reason sent by the callback is 
XmCRCASCADING. 

XmNmappingDelay 

Specifies the amount of time, in milliseconds, between when a CascadeButton 
becomes armed and when it maps its submenu. This delay is only used when the 
widget is within a Popup or Pulldown MenuPane. 

XmNsubMenuId 

Specifies the widget ID for the Pulldown MenuPane to be associated with this Cas- 
cadeButton. The specified MenuPane is displayed when the CascadeButton 
becomes armed. The MenuPane must have been created with the appropriate 
parentage depending on the type of menu used. See XmCreateMenuBar(3X), 
XmCreatePuIIdownMenu(3X), and XmCreatePopupMenu(3X) for more informa- 
tion on the menu systems. 

Inherited Resources 

CascadeButton inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 
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Xm Label Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNalignment 


XmCAlignmcnt 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XinCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabenype 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


dynamic 


CSG 


XmNmarginHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


0 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


dynamic 


CSG 


XmNmarginTop 


XmCMarginTop 


short 


dynamic 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


dynamic 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


'\0' 


CSG 


XmNrecomputeSize 


XroCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 



Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCaliback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThickness 


XmCHighhghtThickness 


short 


0 


CSG 


XmNshadoWThickness 


XmCShadoWThickness 


short 


2 


CSG 


XmN topShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPEaFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCaUbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback or is NULL if this callback 

was not triggered due to an XEvent. 

Behavior 

The default behavior associated with a CascadeButton widget depends on whether the but- 
ton is part of a PopupMenu system or a PulldownMenu system. The RowColumn parent 
determines the mouse button that is used through its XmNrowColumnType and XmNwhi- 
chButton resources. 

Default PopupMenu System 

Btn3Down<EnterWindow>: 

This action arms the CascadeButton and posts the associated submenu after a short 
delay. 

Bt n3Down < LeaveWindow > : 

The action that takes place depends on whether the mouse pointer has moved into 
the submenu associated with this CascadeButton. If the mouse pointer has moved 
into the submenu, then this event is ignored. If not, the CascadeButton is disarmed 
and its submenu unposted. 

<Btn3Up>: 

This action posts the submenu attached to the CascadeButton and enables keyboard 
traversal within the menu. If the CascadeButton does not have a submenu attached, 
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then this event activates the CascadeButton and imposts the menu. 
<Btn3Down>: 

This action disables traversal for the menu and returns the user to drag mode in 
which the menu is manipulated using the mouse. The submenu associated with this 
CascadeButton is posted. 

< Key > Return: 

This event posts the submenu attached to the CascadeButton if keyboard traversal is 
enabled in the menu. If the CascadeButton does not have a submenu attached, then 
this event activates the CascadeButton and unposts the menu. 

Default MenuBar 
<BtnlDown>: 

This event arms both the CascadeButton and the MenuBar and posts the associated 
submenu. If the menu is already active, this event disables traversal for the menu 
and returns the user to the mode where the menu is manipulated using the mouse. 

BtnlDown < EnterWindow > : 

This event unposts any visible MenuPanes if they are associated with a different 
MenuBar entry, arms the CascadeButton, and posts the associated submenu. 

BtnlDown < LeaveWindow > : 

This event disarms the CascadeButton if the submenu associated with it is not 
currently posted or if there is no submenu associated with this CascadeButton. Oth- 
erwise, this event is ignored. 

<BtnlUp>: 

This event posts the submenu attached to the CascadeButton and enables keyboard 
traversal within the menu. If the CascadeButton does not have a submenu attached, 
then this event activates the CascadeButton and unposts the menu. 

< Key > Return: 

This event posts the submenu attached to the CascadeButton if keyboard traversal is 
enabled in the menu. If the CascadeButton does not have a submenu attached, the 
CascadeButton is activated, and unposts the menu. 

Default PulldownMenu System from a MenuBar 

BtnlDown < EnterWindow > : 

This event arms the CascadeButton widget, and after a short delay, posts the associ- 
ated submenu. 

BtnlDown < LeaveWindow > : 

The event is ignored if the mouse pointer has moved into the submenu. In all other 
cases, the CascadeButton is disarmed and its submenu unposted. 

<BtnlUp>: 

This event posts the submenu attached to the CascadeButton and enables keyboard 
traversal within the menu. If the CascadeButton does not have a submenu attached, 
then this event selects the CascadeButton and unposts the menu. 

< BtnlDown >: 

This event disables traversal for the menu and returns the user to the drag mode. 
The submenu associated with this CascadeButton is posted. 

<Key>Return: 

This event posts the submenu attached to the CascadeButton if keyboard traversal is 
enabled in the menu. If the CascadeButton does not have a submenu attached, then 
this event activates the CascadeButton and unposts the menu. 



Hewlett-Packard Company 



-5- 



Aug28,1989 



XmCascadeButton (3X) 



XmCascadeButton (3X) 



Default Translations 

The following are default translations for CascadeButton in a MenuBan 

<BtnDown>: MenuBarSelect() 

<EnterWindow>: MenuBarEnter() 

< LeaveWindow > : MenuBarLeave() 
<BtnUp>: DoSelect() 

< Key > Return: KeySelect() 

< Key > Escape: CleanupMenuBar() 

Default translations for CascadeButton in a Popup or Pulldown MenuPane are: 

<BtnDown>: StartDragO 

<EnterWindow>: DelayedArm() 

< LeaveWindow >: CheckDisarm() 
<BtnUp>: DoSelect() 
<Key>Return: KeySelect() 

< Key > Escape: MenuShellPopdownDone() 

Keyboard Traversal 

The keyboard traversal translations are listed below: 

< Unmap > : UnmapO 
<FocusOut>: FocusOut() 
<FocusIn>: FocusIn() 

< Key > space: Noop() 

< Key > Left: MenuTraverseLeft() 

< Key > Right: MenuTraverseRight() 
<Key>Up: MenuTraverseUpO 

< Key > Down: MenuTraverseDown() 
<Key>Home: Noop() 

RELATED INFORMATION 

Core(3X), XmCascadeButtonHighlight(3X), XmCreateCascadeButton(3X), 
XmCreateMenuBar(3X), XmCreatePulldownMemi(3X), XmCreatePopupMenu(3X), 
XmLabel(3X), XmPrimitive(3X), and XmRowColumn(3X). 
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NAME 

XmCascadeButtonGadget - the CascadeButtonGadget widget class. 

SYNOPSIS 

#include <Xm/CascadeBG.h> 

DESCRIPTION 

CascadeButtonGadget links two MenuPanes or an OptionMenu to a MenuPane. 

It is used in menu systems and must have a RowColumn parent with its XmNrowColumnType 
resource set to XmMENU POPUP, XmMENU PULLDOWN, or XmMENU OPTION. 

It is the only gadget that may have a Pulldown MenuPane attached to is as a submenu. The sub- 
menu is displayed when this gadget is activated within a PopupMenu, a PulldownMenu, or an 
OptionMenu. Its visuals can include a label or pixmap and a cascading indicator when it is in a 
Popop or Pulldown MenuPane; or, it can include only a label or a pixmap when it is in an Option- 
Menu. 

The default behavior associated with a CascadeButtonGadget depends on the type of menu system 
in which it resides. By default, mouse button 1 controls the behavior of the CascadeButtonGadget 
if it resides in a PulldownMenu or an OptionMenu; and, mouse button 3 controls the behavior of 
the CascadeButtonGadget if it resides in a PopupMenu. The actual mouse button used is deter- 
mined by its RowColumn parent. 

A CascadeButtonGadget's visuals differ from most other button gadgets. When the button 
becomes armed, its visuals change from a 2-D to a 3-D look, and it displays the submenu that has 
been attached to it. If no submenu is attached, then it simply changes its visuals. 

When a CascadeButtonGadget within a Pulldown or Popup MenuPane is armed as the result of 
the user moving the mouse pointer into the gadget, it does not immediately display its submenu. 
Instead, it waits a short amount of time to see if the arming was temporary (i.e., the user was sim- 
ply passing through the gadget), or whether the user really wanted the submenu posted. This time 
delay is configurable via XmNmappingDelay. 

CascadeButtonGadget provides a single mechanism for activating the gadget from the keyboard. 
This mechanism is referred to as a keyboard mnemonic. If a mnemonic has been specified for the 
gadget, the user may activate it by simply typing the mnemonic while the CascadeButtonGadget is 
visible. Mnemonics are typically used to interact with a menu via the keyboard interface. 

If in a Pulldown or Popup MenuPane and there is a submenu attached, the XmNmarginBottom, 
XmNmarginRight, and XmNmarginTop resources enlarge to accommodate XmNcascadePixmap. 

Classes 

CascadeButtonGadget inherits behavior and resources from Object, RectObj, XmGadget, 
and XmLabelGadget classes. 

The class pointer is xmCascadeButtonGadgetCIass. 

The class name is XmCascadeButtonGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmCascadeButtonGadget 


Name 


Class 


Type 


Default 


Access 


XmNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNcascadePixmap 


XmCPixmap 


Pixmap 


"menu cascade" 


CSG 


XmNcascadingCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmappingDelay 


XmCMappingDelay 


int 


100 


CSG 


XmNsubMenuId 


XmCMenuWidget 


Widget 


0 


CSG 



XmNactivateCallback 

Specifies the list of callbacks that is called when the user activates the CascadeBut- 
tonGadget, and there is no submenu attached to pop up. The activation occurs by 
releasing a mouse button or by typing the mnemonic associated with the gadget. 
The specific mouse button depends on information in the RowColumn parent. The 
reason sent by the callback is XmCRj^CTTVATE. 

XmNcascadePixmap 

Specifies the cascade pixmap displayed on the right end of the gadget when a Cas- 
cadeButtonGadget is used within a Popup or Pulldown MenuPane and a submenu is 
attached. The LabelGadget class resources XmNmarginRight, XmNmarginTop, and 
XmNmarginBottom may be modified to ensure room is left for the cascade pixmap. 
The default cascade pixmap is an arrow pointing to the right. 

XmNcascadingCallback 

Specifies the list of callbacks that is called just prior to the mapping of the submenu 
associated with the CascadeButtonGadget. The reason sent by the callback is 
XmCRCASCADING. 

XmNmappingDelay 

Specifies the amount of time, in milliseconds, between when a CascadeBut- 
tonGadget becomes armed and when it maps its submenu. This delay is only used 
when the gadget is within a Popup or Pulldown MenuPane. 

XmNsubMenuId 

Specifies the widget ID for the Pulldown MenuPane to be associated with this Cas- 
cadeButtonGadget. The specified MenuPane is displayed when the CascadeBut- 
tonGadget becomes armed. The MenuPane must have been created with the 
appropriate parentage depending on the type of menu used. See 
XmCreatePulldownMenu(3X), XmCreatePopupMenu(3X), and 

XmCreateOptionMenu(3X) for more information on the menu systems. 

Inherited Resources 

CascadeButtonGadget inherits behavior and resources from the following superclasses. For 
a complete description of these resources, refer to the man page for that superclass. 
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XmLabelGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmN alignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


dynamic 


CSG 


XmNmarginHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


0 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


dynamic 


CSG 


XmNmarginTop 


XmCMarginTap 


short 


dynamic 


CSG 


XmNmarginWidth 


XmCMargmWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


'\0' 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirect ion 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 



XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightThickness 


XmCHighlightThickness 


short 


0 


CSG 


XmNshadoWThickness 


XmCShadcwThickness 


short 


2 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



RectObj Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



Callback Information 

The following structure is returned with each callback: 

typed ef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 
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reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback or is NULL if this callback 

was not triggered due to an XEvent. 

Behavior 

The default behavior associated with a CascadeButtonGadget depends on whether the but- 
ton is part of a PopupMenu system, a Pulldown MenuPane in a MenuBar, or an Option- 
Menu system. The RowColumn parent determines the mouse button which is used through 
its XmNrowColumnType and XmNwhichButton resources. 

Default PopupMenu System 
Btn3Down < Enter Window > : 

This action arms the CascadeButtonGadget and posts the associated submenu after 
a short delay. 

Btn3Down < LeaveWindow > : 

The action that takes place depends on whether the mouse pointer has moved into 
the submenu associated with mis CascadeButtonGadget. If the mouse pointer has 
moved into the submenu, then this event is ignored. If not, the CascadeBut- 
tonGadget is disarmed and its submenu unposted. 

<Btn3Up>: 

This action posts the submenu attached to the CascadeButtonGadget and enables 
keyboard traversal within the menu. If the CascadeButtonGadget does not have a 
submenu attached, then this event activates the CascadeButtonGadget and unposts 
the menu. 

<Btn3Down>: 

This action disables traversal for the menu and returns the user to drag mode in 
which the menu is manipulated using the mouse. The submenu associated with this 
CascadeButtonGadget is posted. 

< Key > Return: 

This event posts the submenu attached to the CascadeButtonGadget if keyboard 
traversal is enabled in the menu. If the CascadeButtonGadget does not have a sub- 
menu attached, then this event activates the CascadeButtonGadget and unposts the 
menu. 

Default Pulldown MenuPane from a MenuBar or from an OptionMenu 

BtnlDown<EnterWindow>: 

This event arms the CascadeButtonGadget, and after a short delay, posts the associ- 
ated submenu. 

BtnlDown < LeaveWindow > : 

The event is ignored if the mouse pointer has moved into the submenu. In all other 
cases, the CascadeButtonGadget is disarmed and its submenu unposted. 

<BtnlUp>: 

This event posts the submenu attached to the CascadeButtonGadget and enables 
keyboard traversal within the menu. If the CascadeButtonGadget does not have a 
submenu attached, then this event activates the CascadeButtonGadget and unposts 
the menu. 

<BtnlDown>: 

This event disables traversal for the menu and returns the user to the drag mode. 
The submenu associated with this CascadeButtonGadget is posted. 

<Key>Return: 

This event posts the submenu attached to the CascadeButtonGadget if keyboard 
traversal is enabled in the menu. If the CascadeButtonGadget does not have a 
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submenu attached, then this event activates the CascadeButtonGadget and unposts 
the menu. 

Default OptionMenu 
<BtnlDown>: 

This event arms the CascadeButtonGadget and posts the associated submenu. 
< Key > Return: 

This event posts the associated submenu and enables traversal within the menu. 
Keyboard Traversal 

For information on keyboard traversal, see the man page for XmRowColumn(3X) and its 
sections on behavior and default translations. 



RELATED INFORMATION 

Object(3X), RectObj(3X), XmCascadeButtonHighlight(3), XmCreateCascadeButtonGadget(3X), 
XmCreatePuUdownMenu(3X), XmCreatePopupMenu(3X), XmCreateOptionMenu(3X), 
XmGadget(3X), XmLabelGadget(3X), and XmRowCohimn(3X). 
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NAME 

XmCascadeButtonHighlight - a CascadeButton and CascadeButtonGadget function that sets the 
highlight state. 

SYNOPSIS 

#include <Xm/CascadeB.h> 
#include <Xm/CascadeBG.h> 

void XmCascadeButtonHighlight (cascadeButton, highlight) 
Widget cascadeButton; 
Boolean highlight; 

DESCRIPTION 

XmCascadeButtonHighlight either draws or erases the shadow highlight around the CascadeBut- 
ton or the CascadeButtonGadget 

cascadeButton Specifies the CascadeButton or CascadeButtonGadget to be highlighted or 
unhighlighted. 

highlight Specifies whether to highlight (True) or to unhighlight (False). 

For a complete definition of CascadeButton or CascadeButtonGadget and their associated 
resources, see XmCascadeButton(3X) or XmCascadeButtonGadget(3X). 

RELATED INFORMATION 

XmCascadeButton(3X) and XmCascadeButtonGadget(3X). 
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NAME 

XmCIipboardCancelCopy - a clipboard function that cancels a copy to the clipboard. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

void XmCIipboardCancelCopy (display, window, itemjd) 
Display * display; 

Window window; 
long itemjd; 

DESCRIPTION 

XmCIipboardCancelCopy cancels the copy to clipboard that is in progress and frees up temporary 
storage. When a copy is to be performed, XmClipboardStartCopy allocates temporary storage for 
the clipboard data. XmClipboardCopy fills in the appropriate data into the the temporary 
storage. XmClipboardEndCopy copies the data to the clipboard structure and frees up the tem- 
porary storage structures. If XmCIipboardCancelCopy is called, the XmClipboardEndCopy func- 
tion does not have to be called. A call to XmCIipboardCancelCopy is valid only after a call to 
XmClipboardStartCopy and before a call to XmClipboardEndCopy. 

display Specifies a pointer to the Display structure that was returned in a previous call to 

XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the clip- 

board. The widget's window ID can be obtained by using XtWindow. The same 
application instance should pass the same window ID to each of the clipboard 
functions that it calls. 

itemjd Specifies the number assigned to this data item. This number was returned by a 

previous call to XmClipboardStartCopy. 

RELATED INFORMATION 

XmClipboardCopy(3X), XmClipboardEndCopy(3X), and XmClipboardStartCopy(3X). 
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NAME 

XmClipboardCopy - a clipboard ftinction that copies a data item to temporary storage for later 
copying to clipboard. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardCopy (display, window, itemjd, format juane, buffer, length, private Jd, 
datajd) 

Display * display; 

Window window, 
long itemjd; 
char * format juane; 

char * buffer, 

unsigned long length; 
int private Jd; 
int * datajd; 

DESCRIPTION 

XmClipboardCopy copies a data item to temporary storage. The data item is moved from tem- 
porary storage to the clipboard data structure when a call to XmClipboardEndCopy is made. 
Additional calls to XmClipboardCopy before a call to XmClipboardEndCopy will add additional 
data item formats to the same data item or append data to an existing format. Formats are 
described in the ICCC manual as targets. 

NOTE: Do not call XmClipboardCopy before a call to XmClipboardStartCopy has been made. 
The latter function allocates temporary storage required by XmClipboardCopy. 

If the buffer argument is NULL, the data is considered to be passed by name. When data, which 
has been passed by name, is later requested by another application, the application that owns the 
data receives a callback with a request for the data. The application that owns the data must then 
transfer the data to the clipboard with the XmClipboardCopyByName function. When a data item 
that was passed by name is deleted from the clipboard, the application that owns the data receives 
a callback that states that the data is no longer needed. 

For information on the callback function, see the callback argument description for XmClip- 
boardStartCopy. 

display 

window 



itemjd 

format jiame 

buffer 
length 
private Jd 

data id 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

Specifies the number assigned to this data item. This number was 
returned by a previous call to XmClipboardStartCopy. 

Specifies the name of the format in which the data item is stored on the 
clipboard. Format is known as target in the ICCC manual. 

Specifies the buffer from which the clipboard copies the data. 

Specifies the length of the data being copied to the clipboard. 

Specifies the private data that the application wants to store with the 
data item. 

Specifies an identifying number assigned to the data item that uniquely 
identifies the data item and the format. This argument is required only 
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for data that is passed by name. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCopyByName(3X), XmClipboardEndCopy(3X), and XmClipboardStartCopy(3X). 
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NAME 

XmCIipboardCopyByName - a clipboard function that copies a data item passed by name. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmCIipboardCopyByName (display, window, datajd, buffer, length, private Jd) 

Display * display; 

Window window, 

int datajd; 

char * buffer, 

unsigned long lengih; 

int private Jd; 



DESCRIPTION 

XmCIipboardCopyByName copies the actual data for a data item that was previously passed by 
name to the clipboard. Data is considered to be passed by name when a call to XmClipboardCopy 
is made with a NULL buffer parameter. Additional calls to this function append new data to the 
existing data. When making additional calls to this function, the clipboard should be locked to 
ensure the integrity of the clipboard data. To lock the clipboard, use XmClipboardLock. Unlock 
the clipboard when copying is completed; to unlock the clipboard, use XmClipboardUnlock. 



display Specifies a pointer to the Display structure that was returned in a previous 

call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each of 
the clipboard functions that it calls. 

datajd Specifies an identifying number assigned to the data item that uniquely 

identifies the data item and the format. This number was assigned by 
XmClipboardCopy to the data item. 

buffer Specifies the buffer from which the clipboard copies the data. 

length Specifies the number of bytes in the data item. 

private Jd Specifies the private data that the application wants to store with the data 

item. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCopy(3X), XmClipboardLock(3X), XmClipboardStartCopy(3X), and 
XmClipboardUnlock(3X). 
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NAME 

XmClipboardEndCopy - a clipboard function that ends a copy to the clipboard. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardEndCopy {display, window, itemjd) 
Display * display; 

Window window, 
long item id; 



DESCRIPTION 

XmClipboardEndCopy locks the clipboard from access by other applications, places data in the 
clipboard data structure, and unlocks the clipboard. Data items copied to the clipboard by 
XmClipboardCopy are not actually entered in the clipboard data structure until the call to 
XmClipboardEndCopy. 

This function also frees up temporary storage that was allocated by XmCIipboardStartCopy, 
which must be called before XmClipboardEndCopy. The latter function should not be called if 
XmClipboardCancelCopy has been called. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

itemjd Specifies the number assigned to this data item. This number was 

returned by a previous call to XmCIipboardStartCopy. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCancelCopy(3X), XmClipboardCopy(3X) and XmClipboardStartCopy(3X). 
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NAME 

XmClipboardEndRetrieve - a clipboard ftinction that ends a copy from the clipboard. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardEndRetrieve {display, window) 
Display * display; 

Window window, 

DESCRIPTION 

XmClipboardEndRetrieve suspends copying data incrementally from the clipboard. It tells the 
clipboard routines that the application is through copying an item from the clipboard. Until this 
function is called, data items can be retrieved incrementally from the clipboard by calling XmClip- 
boardRetrieve. If the application calls XmClipboardStartRetrieve, it must call XmClipboardEn- 
dRetrieve. If data is not being copied incrementally, XmClipboardStartRetrieve and XmClipboar- 
dEndRetrieve do not need to be called. 



display 
window 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 



RETURN VALUE 

ClipboardSuccess 

ClipboardLocked 



The function is successful. 

The function failed because the clipboard was locked by another applica- 
tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardRetrieve(3X), XmClipboardStartCopy(3X), and XmClipboardStartRetrieve(3X). 
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NAME 



XmClipboardlnquireCount - a function that returns the number of data item formats. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardlnquireCount (display, window, count, maxjormatjiamejength) 
Display * display} 

Window window} 
int * count; 

int * maxjormatjiamejength', 

DESCRIPTION 

XmClipboardlnquireCount returns the number of data item formats available for the data item in 
the clipboard. This function also returns the maximum name length for all formats in which the 
data item is stored. 



display 
window 

count 

max Jormat name length 



Specifies a pointer to the Display structure that was returned 
in a previous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application win- 
dow to the clipboard. The widget's window ID can be 
obtained by using XtWindow. The same application instance 
should pass the same window ID to each of the clipboard func- 
tions that it calls. 

Returns the number of data item formats available for the data 
item in the clipboard. If no formats are available, this argu- 
ment equals zero. The count includes the formats that were 
passed by name. 

Specifies the maximum length of all format names for the data 
item in the clipboard. 



RETURN VALUE 

ClipboardSuccess 

ClipboardLocked 



ClipboardNoData 



The function is successful. 

The function failed because the clipboard was locked by 
another application. The application can continue to call the 
function again with the same parameters until the lock goes 
away. This gives the application the opportunity to ask if the 
user wants to keep trying or to give up on the operation. 

The function could not find data on the clipboard correspond- 
ing to the format requested. This could occur because the clip- 
board is empty; there is data on the clipboard but not in the 
requested format; or the data in the requested format was 
passed by name and is no longer available. 



RELATED INFORMATION 

XmCIipboardStartCopy(3X). 
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NAME 

XmClipboardlnquireFormat - a clipboard function that returns a specified format name. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardlnquireFormat {display, window, index, format namejyuf, buffer Jen, 
copied Jen) 

Display * display; 

Window window; 

int index; 

char * format jtamebufi 

unsigned long buffer Jen; 

unsigned long * copied Jen; 



DESCRIPTION 

XmClipboardlnquireFormat returns a specified format name for the data item in the clipboard. 
If the name must be truncated, the function returns a warning status. 



display Specifies a pointer to the Display structure that was returned in a pre- 

vious call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to 

the clipboard. The widget's window ID can be obtained by using 
XtWindow. The same application instance should pass the same win- 
dow ID to each of the clipboard functions that it calls. 

index Specifies which of the ordered format names to obtain. If this index i 

is greater than the number of formats for the data item, this function 
returns a zero in the copied len argument. 

format jtamejyuf Specifies the buffer that receives the format name. 

buffer Jen Specifies the number of bytes in the format name buffer. 

copied Jen Specifies the number of bytes in the string copied to the buffer. If this 

argument equals zero, there is no nth format for the data item. 



The function is successful. 

The function failed because the clipboard was locked by another appli- 
cation. The application can continue to call the function again with 
the same parameters until the lock goes away. This gives the applica- 
tion the opportunity to ask if the user wants to keep trying or to give 
up on the operation. 

ClipboardTruncate The data returned is truncated because the user did not provide a 

buffer that was large enough to hold the data. 

ClipboardNoData The function could not find data on the clipboard corresponding to 

the format requested. This could occur because the clipboard is 
empty; there is data on the clipboard but not in the requested format; 
or the data in the requested format was passed by name and is no 
longer available. 



RETURN VALUE 

ClipboardSuccess 

ClipboardLocked 



RELATED INFORMATION 

XmClipboardStartCopy(3X). 
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NAME 



XmClipboardlnquireLength - a clipboard function that returns the length of the stored data. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardlnquireLength {display, window, format jiame, length) 
Display * display; 

Window window, 
char * format _name\ 

unsigned long * length; 

DESCRIPTION 

XmClipboardlnquireLength returns the length of the data stored under a specified format name 
for the clipboard data item. If no data is found for the specified format, or if there is no item on 
the clipboard, this function returns a value of zero. 

Any format passed by name is assumed to have the length passed in a call to XmClipboardCopy, 
even though the data has not yet been transferred to the clipboard in that format. 



display 
window 



format jiame 
length 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

Specifies the name of the format for the data item. 

Specifies the length of the next data item in the specified format. This 
argument equals zero if no data is found for the specified format, or if 
there is no item on the clipboard. 



RETURN VALUE 

ClipboardSuccess 

ClipboardLocked 



ClipboardNoData 



The function is successful. 

The function failed because the clipboard was locked by another applica- 
tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 

The function could not find data on the clipboard corresponding to the 
format requested. This could occur because the clipboard is empty; 
there is data on the clipboard but not in the requested format; or the 
data in the requested format was passed by name and is no longer avail- 
able. 



RELATED INFORMATION 

XmClipboardCopy(3X) and XmClipboardStartCopy(3X). 
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NAME 

XmClipboardlnquirePendingltems - a clipboard (unction that returns a list of data id /private Jd 
pairs. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardlnquirePendingltems (display, window, format juane, itemjist, count) 

Display * display; 

Window window, 

char * format jiame; 

XmClipboardPendingList * itemjist; 

unsigned long * count, 



DESCRIPTION 

XmClipboardlnquirePendingltems returns a list of data Jd/ private Jd pairs for the specified for- 
mat name. A data item is considered pending if the application originally passed it by name, the 
application has not yet copied the data, and the item has not been deleted from the clipboard. 
The application is responsible for freeing the memory provided by this function to store the list. 

This function is used by an application when exiting to determine if the data that is passed by 
name should be sent to the clipboard. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

format jtame Specifies a string that contains the name of the format for which the list 

of data id/private id pairs is to be obtained. 

itemjist Specifies the address of the array of data id/private id pairs for the 

specified format name. This argument is a type XmClipboardPen- 
dingList. The application is responsible for freeing the memory pro- 
vided by this function for storing the list. 

item_count Specifies the number of items returned in the list. If there is no data for 

the specified format name, or if there is no item on the clipboard, this 
argument equals zero. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardStartCopy(3X). 
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NAME 

XmClipboardLock - a clipboard ftinction that locks the clipboard. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardLock (display, window) 
Display * display; 

Window window, 

DESCRIPTION 

XmClipboardLock locks the clipboard from access by another application until XmClipboardUn- 
lock is called. All clipboard functions lock and unlock the clipboard to prevent simultaneous 
access. This function allows the application to keep the clipboard data from changing between 
calls to the inquire and other clipboard functions. The application does not need to lock the clip- 
board between calls to XmClipboardStartCopy and XmClipboardEndCopy or to XmClip- 
boardStartRetrieve and XmClipboardEndRetrieve. 

The application should lock the clipboard before multiple calls to XmClipboardCopyByName and 
should unlock the clipboard after completion. 

If the clipboard is already locked by another application, XmClipboardLock returns an error 
status. Multiple calls to this function by the same application increases the lock level. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCopyByName(3X),XmClipboardEndCopy(3X),XmClipboardEndRetrieve(3X), 
XmClipboardStartCopy(3X), XmCIipboardStartRetrieve(3X), and XmClipboardUnlock(3X). 
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NAME 

XmCIipboardRegisterFormat - a clipboard function that registers a new format. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmCIipboardRegisterFoimat (display, formal jtame, format Jength) 
Display * display, 

char * format jtame; 

unsigned long format Jengfh; 

DESCRIPTION 

XmCIipboardRegisterFormat registers a new format. Each format stored on the clipboard should 
have a length associated with it; this length must be known to the clipboard routines. Formats are 
known as targets in the ICCC manual. All of the formats specified by the ICCCM conventions are 
preregistered. Any other format that the application wants to use must either be 8-bit data or be 
registered via this routine. Failure to register the length of the data results in incompatible appli- 
cations across platforms having different byte swapping orders. 

display Specifies a pointer to the Display structure that was returned in a 

previous call to XOpenDisplay or XtDisplay. 

format jtame Specifies the string name for the new format (target). 

format Jength Specifies the format length in bits (8, 16, or 32). 

RETURN VALUE 

ClipboardBadFormat The format jtame must not be NULL, and the format Jength must 

be 8, 16, or 32. 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another 

application. The application can continue to call the function 
again with the same parameters until the lock goes away. This 
gives the application the opportunity to ask if the user wants to 
keep trying or to give up on the operation. 



RELATED INFORMATION 

XmClipboardStartCopy(3X). 
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NAME 

XmClipboardRetrieve - a clipboard function that retrieves a data item from the clipboard. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardRetrieve (display, window, format jiame, buffer, length, num bytes, private Jd) 

Display * display; 

Window window, 

char * format jiame; 

char * buffer, 

unsigned long length; 

unsigned long * numbytes; 

int * private Jd; 



DESCRIPTION 

XmClipboardRetrieve retrieves the current data item from clipboard storage. It returns a warning 
if the clipboard is locked; if there is no data on the clipboard; or, if the data needs to be truncated 
because the buffer length is too short 

Between a call to XmClipboardStartRetrieve and XmClipboardEndRetrieve, multiple calls to 
XmClipboardRetrieve with the same format name will result in data being incrementally copied 
from the clipboard until the data in that format has all been copied. 

The return value ClipboardTruncate from calls to XmClipboardRetrieve indicates that more data 
remains to be copied in the given format. It is recommended that any calls to the Inquire func- 
tions that the application needs to make to effect the copy from the clipboard be made between 
the call to ClipboardStartRetrieve and the first call to XmClipboardRetrieve. That way, the appli- 
cation does not need to call XmClipboardLock and XmClipboardUnlock. Applications do not 
need to use XmClipboardStartRetrieve and XmClipboardEndRetrieve, in which case XmClip- 
boardRetrieve works as it did before. 



display 
window 

format jiame 

buffer 

lengfh 
num bytes 
private Jd 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using Xt Window. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

Specifies the name of a format in which the data is stored on the clip- 
board. 

Specifies the buffer to which the application wants the clipboard to copy 
the data. 

Specifies the length of the application buffer. 

Specifies the number of bytes of data copied into the application buffer. 

Specifies the private data stored with the data item by the application 
that placed the data item on the clipboard. If the application did not 
store private data with the data item, this argument returns zero. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
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opportunity to ask if the user wants to keep trying or to give up on the 
operation. 

ClipboardTruncate The data returned is truncated because the user did not provide a buffer 
that was large enough to hold the data. 

ClipboardNoData The function could not find data on the clipboard corresponding to the 
format requested. This could occur because the clipboard is empty; 
there is data on the clipboard but not in the requested format; or the 
data in the requested format was passed by name and is no longer avail- 
able. 



RELATED INFORMATION 

XmClipboardEndRetrieve(3X), XmClipboardLock(3X), XmClipboardStartCopy(3X), 
XmClipboardStartRetrieve(3X), and XmClipboardUnlock(3X). 
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NAME 

XmClipboardStartCopy - a clipboard function that sets up a storage and data structure. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 



int XmClipboardStartCopy {display, window, clipjabel, timestamp, widget, callback, itemjd) 

Display * display, 

Window window, 

XmString clipjabel', 

Time timestamp', 

Widget widget; 

VoidProc callback; 

long * item id; 



DESCRIPTION 

XmClipboardStartCopy sets up storage and data structures to receive clipboard data. An applica- 
tion calls this function during a cut or copy operation. The data item that these structures receive 
then becomes the next data item in the clipboard. 

Copying a large piece of data to the clipboard can take time. It is possible that, once copied, no 
application will ever request that data. The OSF/Motif Toolkit provides a mechanism so that an 
application does not need to actually pass data to the clipboard until the data has been requested 
by some application. 

Instead, the application passes format and length information in XmClipboardCopy to the clip- 
board functions, along with a widget ID and a callback function address that is passed in XmClip- 
boardStartCopy. The widget ID is needed for communications between the clipboard functions in 
the application that owns the data and the clipboard functions in the application that requests the 
data. 

The callback functions are responsible for copying the actual data to the clipboard via XmClip- 
boardCopyByName. The callback function is also called if the data item is removed from the clip- 
board, and the actual data is therefore no longer needed. 



display 
window 

clipjabel 



timestamp 
widget 



callback 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

Specifies the label to be associated with the data item. This argument is 
used to identify the data item, for example, in a clipboard viewer. An 
example of a label is the name of the application that places the data in 
the clipboard. 

Specifies the time of the event that triggered the copy. 

Specifies the ID of the widget that will receive messages requesting data 
previously passed by name. This argument must be present in order to 
pass data by name. Any valid widget ID in your application can be used 
for this purpose and all the message handling is taken care of by the cut 
and paste functions. 

Specifies the address of the callback function that is called when the clip- 
board needs data that was originally passed by name. This is also the 
callback to receive the delete message for items that were originally 
passed by name. This argument must be present in order to pass data 
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by name. 

itemjd Specifies the number assigned to this data item. The application uses 

this number in calls to XmClipboardCopy, XmClipboardEndCopy, and 
XmClipboardCancelCopy. 



For more information on passing data by name, see XmClipboardCopy(3X) and 
XmClipboardCopyByName(3X). 

The widget and callback arguments must be present in order to pass data by name. The callback 
format is as follows: 



function name 

Widget widget; 

int * datajd; 

int * private} 

int * reason; 



widget Specifies the ID of the widget passed to this function. 

datajd Specifies the identifying number returned by XmClipboardCopy, which 

identifies the pass-by-name data. 

private Specifies the private information passed to XmClipboardCopy. 

reason Specifies the reason, which is either 

XmCRCLIPBOARDDATA DELETE or 
XmCR CLIPBOARD DATA~REQUEST. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCanceICopy(3X),XmCIipboardCopy(3X),XmClipboardCopyByName(3X), 
XmClipboardEndCopy(3X), XmClipboardEndRetrieve(3X), XmClipboardInquireCount(3X), 
XmClipboardlnquireFormat (3X) , XmClipboardInquireLength(3X) , 
XmClipboardInquirePendingItems(3X), XmClipboardLock(3X), 

XmClipboardRegisterFormat(3X), XmClipboardRetrieve(3X), XmClipboardStartRetrieve(3X), 
XmClipboardUndoCopy(3X), XmClipboardUnlock(3X), and XmClipboardWithdrawFormat(3X). 
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NAME 

XmCIipboardStartRetrieve - a function that starts a copy from the clipboard. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmCIipboardStartRetrieve (display, window, timestamp) 
Display * display; 

Window window, 
Time timestamp', 

DESCRIPTION 

XmCIipboardStartRetrieve tells the clipboard routines that the application is ready to start copy- 
ing an item from the clipboard. The clipboard will be locked by this routine, and will stay locked 
until XmCIipboardEndRetrieve is called. Between a call to XmCIipboardStartRetrieve and 
XmClipboardEndRetrieve, multiple calls to XmClipboardRetrieve with the same format name will 
result in data being incrementally copied from the clipboard until the data in that format has all 
been copied. 

The return value ClipboardTruncate from calls to XmClipboardRetrieve indicates that more data 
remains to be copied in the given format. It is recommended that any calls to the Inquire func- 
tions that the application needs to make to effect the copy from the clipboard be made between 
the call to XmCIipboardStartRetrieve and the first call to XmClipboardRetrieve. That way, the 
application does not need to call XmClipboardLock and XmClipboardUnlock. Applications do 
not need to use XmCIipboardStartRetrieve and XmClipboardEndRetrieve, in which case XmClip- 
boardRetrieve works as it did before. 



display 
window 

timestamp 



Specifies a pointer to the Display structure that was returned in a previ- 
ous call to XOpenDisplay or XtDisplay. 

Specifies a widget's window ID that relates the application window to the 
clipboard. The widget's window ID can be obtained by using Xt Window. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

Specifies the time of the event that triggered the copy. 



RETURN VALUE 

ClipboardSuccess 

ClipboardLocked 



The function is successful. 

The function failed because the clipboard was locked by another applica- 
tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardEndRetrieve(3X),XmClipboardInquireCount(3X), 
XmClipboardInquireFormat(3X), XmCUpboardInquireLength(3X), 

XmClipboardInquirePendingItems(3X), XmClipboardLock(3X), XmClipboardRetrieve(3X), 
XmClipboardStartCopy(3X), and XmClipboardUnlock(3X). 
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NAME 

XmClipboardUndoCopy - a clipboard ftinction that deletes the last item placed on the clipboard. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardUndoCopy {display, window) 
Display * display; 

Window window, 



DESCRIPTION 

XmClipboardUndoCopy deletes the last item placed on the clipboard if the item was placed there 
by an application with the passed display and window arguments. Any data item deleted from the 
clipboard by the original call to XmClipboardCopy is restored. If the display or window IDs do 
not match the last copied item, no action is taken, and this function has no effect. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 
tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardLock(3X) and XmClipboardStartCopy(3X). 



Hewlett-Packard Company 



-1- 



Jul 27, 1989 



XmClipboardUnk>ck(3X) 



XmCIipboardUnIock(3X) 



NAME 

XmClipboardUnlock - a clipboard function that unlocks the clipboard. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardUnlock (display, window, remove _all Jocks) 
Display * display; 

Window window; 
Boolean remove all locks; 



DESCRIPTION 

XmClipboardUnlock unlocks the clipboard, enabling it to be accessed by other applications. 

If multiple calls to XmClipboardLock have occurred, then the same number of calls to XmClip- 
boardUnlock is necessary to unlock the clipboard, unless remove jM Jocks is set to True. 

The application should lock the clipboard before multiple calls to XmClipboardCopyByName and 
should unlock the clipboard after completion. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

remove jdl Jocks Indicates that all nested locks should be removed, when True. When 

False, indicates that only one level of lock should be removed. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCancelCopy(3X) , XmClipboardCopy(3X) , XmClipboardCopyByName(3X), 
XmClipboardEndCopy(3X), XmClipboardEndRetrieve(3X), XmCIipboardInquireCount(3X), 
XmClipboardlnquireFormat (3X) , XmClipboardInquireLength(3X), 
XmClipboardInquirePendingItems(3X), XmClipboardLock(3X), 

XmClipboardRegisterFormat(3X), XmClipboardRetrieve(3X), XmClipboardStartCopy(3X), 
XmClipboardStartRetrieve(3X), XmCIipboardUndoCopy(3X), and 
XmClipboardWithdrawFormat(3X). 
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NAME 

XmClipboardWithdrawFormat - a clipboard function that indicates that the application no 
longer wants to supply a data item. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xm/CutPaste.h> 

int XmClipboardWithdrawFormat (display, window, datajd) 
Display * displays 

Window window, 
int data id; 



DESCRIPTION 

XmClipboardWithdrawFormat indicates that the application will no longer supply a data item to 
the clipboard that the application had previously passed by name. 



display Specifies a pointer to the Display structure that was returned in a previ- 

ous call to XOpenDisplay or XtDisplay. 

window Specifies a widget's window ID that relates the application window to the 

clipboard. The widget's window ID can be obtained by using XtWindow. 
The same application instance should pass the same window ID to each 
of the clipboard functions that it calls. 

datajd Specifies an identifying number assigned to the data item that uniquely 

identifies the data item and the format. This was assigned to the item 
when it was originally passed byXmClipboardCopy. 



RETURN VALUE 

ClipboardSuccess The function is successful. 

ClipboardLocked The function failed because the clipboard was locked by another applica- 

tion. The application can continue to call the function again with the 
same parameters until the lock goes away. This gives the application the 
opportunity to ask if the user wants to keep trying or to give up on the 
operation. 



RELATED INFORMATION 

XmClipboardCopy(3X) and XmClipboardStartCopy(3X). 
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NAME 

XmCommand - the Command widget class. 

SYNOPSIS 

#inchide <Xm/Command.h> 

DESCRIPTION 

Command is a special-purpose composite widget for command entry that provides a built-in com- 
mand history mechanism. Command includes a command line text input field, a command line 
prompt, and a command history list region. 

One additional WorkArea child maybe added to the Command after creation. 

Whenever a command is entered, it is automatically added to the end of the command history list 
and made visible. This does not change the selected item in the list, if there is one. 

Many of the new resources specified for Command are actually SelectionBox resources that have 
been renamed for clarity and ease of use. 

Classes 

XmCommand inherits behavior and resources from Core, Composite, Constraint, 
XmManager, XmBuIletinBoard, and XmSelectionBox classes. 

The class pointer is xmCommandWidgetClass. 

The class name is XmCommand. 



New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmCommand Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNcommand 


XmCTextString 


XmString 


NULL 


CSG 


XmNcommandCbaDgedCaUback 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNoogmvindRnteredCallback 


XmCCallback 


XtCaUbadcList 


NULL 


C 


XmNhistoryltems 


XmCItems 


XmStringTable 


NULL 


CSG 


XmNhistoryltemCount 


XmCItemCount 


int 


0 


CSG 


XmNhistoryMaxItems 


XmCMaxItems 


int 


100 


CSG 


XmNhistoiyVisibleltemCount 


XmCVisibleltemCount 


int 


8 


CSG 


XmNpromptString 


XmCXmString 


XmString 


">" 


CSG 



XmNcommand 

Contains the current command line text. This is the XmNtextString resource in 
SelectionBox, renamed for Command. This resource can also be modified via 
XmCommandSetValue and XmCommandAppendValue functions. The command 
area is a Text widget 

XmNcommandChangedCallback 

Specifies the list of callbacks that is called when the value of the command changes. 
The callback reason is XmCR_COMMAND_CHANGED. This is equivalent to the 
XmNvalueChangedCallback "of the Text widget, except that an 
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XmCommandCallbackStructure is returned, loaded with the XmString. 

XmNcommandEnteredCallback 

Specifies the list of callbacks that is called when a command is entered in the Com- 
mand. The callback reason is XmCRCOMMANDENTERED. An XmCommand- 
Callback structure is returned. ~ 

XmNhistoryltems 

Lists XmString items that make up the contents of the history list. This is the 
XmNlistltems resource in SelectionBox, renamed for Command. 

XmNhistoryltemCount 

Specifies the number of XntStrings in XmNhistoryltems. This is the XmNIistltem- 
Count resource in SelectionBox, renamed for Command. 

XmNhistoryMaxItems 

Specifies the maximum number of items allowed in the history list. Once this 
number is reached, the first list item is removed from the list for each new item 
added to the list, that is, for each command entered. 

XmNhistoryVisibleltemCount 

Specifies the number of items in the history list that should be visible at one time. 
In effect, it sets the height (in lines) of the history list window. This is the XmNvisi- 
bleltemCount resource in SelectionBox, renamed for Command. 

XmNpromptString 

Prompts for the command line. This is the XmNselectionLabelString resource in 
SelectionBox, renamed for Command. 

Inherited Resources 

Command inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



Xm SelectionBox Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNapplyCallback 


XmCCallback 


XtCallbackList 


NULL 


N/A 


XmNapplyLabelString 


XmCAppr/LabelString 


XmString 


"Apply" 


N/A 


XmNcancelCallback 


XmCCallback 


XtCallbackList 


NULL 


N/A 


XmNcancelLabelString 


XmCXmString 


XmString 


"Cancel" 


N/A 


XmNdialogfype 


XmCDialogiype 


unsigned char 


XmDIALOGCOMMAND 


G 


XmNhelpLabelString 


XmCXmString 


XmString 


"Help" 


N/A 


XmNlistltemCount 


XmCItemCount 


int 


0 


N/A 


XmNlistltems 


XmCltems 


XmStringList 


NULL 


N/A 


XmNlistLabelString 


XmCXmString 


XmString 


NULL 


N/A 


XmNlistVisibleltemCount 


XmCVisibleltemCount 


int 


8 


N/A 


XmNminimizeButtons 


XmCminimizeButtons 


Boolean 


False 


N/A 


XmNmustMatch 


XmCMustMatch 


Boolean 


False 


N/A 


XmNnoMatchCallback 


XmCCallback 


XtCallbackList 


NULL 


N/A 


XmNokCallbadc. 


XmCCallback 


XtCallbackList 


NULL 


N/A 


XmNokLabelString 


XmCXmString 


XmString 


"OK" 


N/A 


XmNselectionLabelString 


XmCXmString 


XmString 


"Selection" 


CSG 


XmNtextAccelerators 


XmCTextAccelerators 


XtTranslations 


see description 


C 


XmNtextColumns 


XmCTextColumns 


int 


20 


CSG 


XmNtextValue 


XmCTextValue 


XmString 


NULL 


N/A 
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XmBuIfetinBoard Resource Set 


Name 


Class 




Default 




XmNallowOverlap 


AnK-AiiOwv-A'criap 


Boolean 


True 


N/A 


XinNftiif nl Ipmanagc 


XmGAutoUnm&nage 


Boolean 


False 


csg 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


N/A 


XmNcancelButton 


ajih^ wiage i 


WlOgcl 


NULL 


XI /A 

N/A 


XmNdefaultButton 


xmcwiaget 


widget 


NULL 


N/A 


XmNdefaultPosition 


XmCDefaultPosition 


Boolean 


False 


CSG 


AJniNaiaiogiHyic 


XmCDialogStyie 


unsigned char 


dynamic 


CSG 


XmNdialogfTitle 


XmCXmString 


XmString 


NULL 


CSG 


APiNtocuscaiiDacK 


V.n /"VV 111.*. 


XtCailDaCKLdSt 


NULL 


C 


AJniN laocir ontList 


XmCLabelFontList 


XmFontList 


NULL 


CSG 


XmNmapCaUback 


AJIKA^allDaCX 


AtLallDacKLlSt 


NULL 


C 


XinNmarginHeight 


XinCMarginHeight 


short 


10 


CSG 


AmrN margin wiuin 


AnK^Marginwioxn 


short 


10 


CSG 




XmCNoResize 






CSG 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZE NONE 


CSG 


XinNshadoWiype 


XinCShadoWiype 


unsigned char 


XmSHADOW OUT 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 


XmNtcxtFontList 


XmCTextFontList 


XmFontList 


NULL 


CSG 


XmNtextTranslations 


XmCTranslations 


XtTranslations 


NULL 


C 


XrnNunmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmManager Resource Set 


Name 


Class 


Typ« 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShackwPixmap 


XmCBottomShacJawPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHigblightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadcmThidtncss 


XrnCShadov/Thickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadcwPixmap 


XmCTopShaoowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnirType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAocelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbadcgroundPixmap 


XmCPixmap 


Pixmap 


XmllNSPECIFlED PIXMAP 


CSG 


XmNbordeiColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbaclcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmN mappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscrecn 


XmCScrcen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int reason; 

XEvent * event; 

XmString value; 

int length; 
} XmConunandCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

value Specifies the XmString in the CommandArea. 

length Specifies the size of the command in XmString. 

Behavior 

Command behavior is summarized below. 
<Key>: 

When any change is made to the text edit widget, the callbacks for XmNcom- 
mandChangedCallback are called. 

< Key > Return: 

When the Return key is pressed, the callbacks for XmNcommandEnteredCallback 
and XmNcommandChangedCallback are called. 

<Key>Up or <Key>Down: 

When the up or down key is pressed within the Text subwidget of Command, the 
text value is replaced with the previous or next item in the List subwidget. The 
selected item in the list is also changed to the previous or the next item. The call- 
backs for XmNcommandChangedCallback are called. 
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< DoubleClick >: 

When an item in the List subwidget is double clicked, that item is selected and 
added to the end of the list in one action. The callbacks for XmNcommandEntered- 
Callback and XmNcommandChangedCallback are called. 

<Key>Fl: 

When the Function Key 1 is pressed, the callbacks for XmNhelpCallback are called. 
<FocusIn>: 

When a Focusln event is generated on the widget window, the callbacks for 
XmNfocusCallback are called. 

<MapWindow>: 

When a Command that is the child of a DialogShell is mapped, the callbacks for 
XmNmapCallback are invoked. When a Command that is not the child of a Dialog- 
Shell is mapped, the callbacks are not invoked. 

< UnmapWindow > : 

When a Command that is the child of a Dialogshell is unmapped, the callbacks for 
XmNunmapCallback are invoked. When a Command that is not the child of a Dia- 
logShell is unmapped, the callbacks are not invoked. 



Default Translations 

Command inherits default translations from SelectionBox. 



Default Accelerators 

The default accelerator translations added to descendants of a BulletinBoard if the parent of 
the BulletinBoard is a DialogShell are: 



#override 

<Key>Fl: Help() 

< Key > Return: Return() 
<Key>KP_Enten Return() 

Default Text Accelerators 

The default text accelerators inherited from SelectionBox are: 

#override 

<Key>Up: UpOrDown(O) 

<Key>DowiK UpOrDown(l) 

<Key>Fl: Help() 

< Key > Return: Return() 
<Key>KP_Enten ReturnQ 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), 
XmConunandAppendValue(3X), XmConunandError(3X), XmConunandGetChild(3X), 
XmContmandSetValue(3X), XmCreateCommand (3X) , XmManager(3X), and 
XmSelectionBox(3X). 
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XmCommandAppendValue (3X) 



NAME 

XmCommandAppendValue - a Command function that appends the passed XmString to the end 
of the string displayed in the command area of the widget. 

SYNOPSIS 

#include <Xm/Command.h> 

void XmCommandAppendValue (widget, command) 
Widget widget; 

XmString command; 

DESCRIPTION 

XmCommandAppendValue appends the passed XmString to the end of the string displayed in the 
command area of the Command widget. 

widget Specifies the Command widget ID. 

command Specifies the passed XmString. 

For a complete definition of Command and its associated resources, see XmCommand(3X). 

RELATED INFORMATION 
XmCommand(3X). 
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XmCommandError (3X) 



NAME 

XmCommandError - a Command function that displays an error message. 

SYNOPSIS 

#include <Xm/Command.h> 

void XmCommandError (widget, error) 
Widget widget; 

XmString error; 
DESCRIPTION 

XmCommandError displays an error message in the history area of the Command widget. The 
XmString error is displayed until the next command entered occurs. 

widget Specifies the Command widget ID. 

error Specifies the passed XmString. 

For a complete definition of Command and its associated resources, see XmCommand(3X). 

RELATED INFORMATION 

XmCommand(3X). 
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NAME 

XmCommandGetChild - a Command function that is used to access a component 

SYNOPSIS 

#include <Xm/Command.h> 

Widget XmCommandGetChild (widget, child) 
Widget widget; 

unsigned char child; 
DESCRIPTION 

XmCommandGetChild is used to access a component within a Command. The parameters given 
to the function are the Command widget and a value indicating which child to access. 

widget Specifies the Command widget ID. 

child Specifies a component within the Command. The following are legal values for 

this parameter 

• XmDIALOG COMMAND TEXT. 

• XmDIALOG PROMPT LABEL. 

• XmDIALOGHISTORYLIST. 

For a complete definition of Command and its associated resources, see XmCommand(3X). 

RETURN VALUE 

Returns the widget ID of the specified Command child. 

RELATED INFORMATION 
XmCommand(3X). 
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XmCommandSetValue (3X) 



NAME 

XmCommandSetValue - a Command function that replaces a displayed string. 

SYNOPSIS 

#include <Xm/Command.h> 

void XmCommandSetValue (widget, command) 
Widget widget; 

XmString command; 
DESCRIPTION 

XmCommandSetValue replaces the string displayed in the command area of the Command widget 
with the passed XmString. 

widget Specifies the Command widget ID. 

command Specifies the passed XmString. 

For a complete definition of Command and its associated resources, see XmCommand(3X). 

RELATED INFORMATION 
XmCommand(3X). 
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XmConvertUnits (3X) 



NAME 

XmConvertUnits - a function that converts a value in one unit type to another unit type. 



SYNOPSIS 

#include <Xm/Xm.h> 

int XmConvertUnits (widget, orientation, fromjinitjype, from value, tojinitjype) 



Widget widget; 

int orientation; 

int fromjinit type; 

int from value; 

int tojinitjype; 



DESCRIPTION 

XmConvertUnits converts the value and returns it as the return value from the function. 



widget Specifies the widget for which the data is to be converted. 

orientation Specifies whether the converter uses the horizontal or vertical screen 

resolution when performing the conversions. Can have values of 
XmHORIZONTAL or XmVERTICAL. 

fromjinitjype Specifies the current unit type of the supplied value. 

pom value Specifies the value to be converted. 

tojinitjype Converts the value to the unit type specified. 



The parameters fromjinitjype and tojinitjype can have the following values: 

• XmPIXELS - all values provided to the widget are treated as normal pixel values. This is the 
default for the resource. 

• XmlOOTH_MILLIMETERS - all values provided to the widget are treated as 1/100 millime- 
ter. 

• XmlOOOTHJNCHES - all values provided to the widget are treated as 1/1000 inch. 

• XmlOOTH POINTS - all values provided to the widget are treated as 1/100 point. A point is 
a unit typically used in text processing applications and is defined as 1/72 inch. 

• Xml00TH_FONT_UNrrS - all values provided to the widget are treated as 1/100-font unit. 
The value to be used for the font unit is determined in one of two ways. The resource 
XmNfont can be used in a defaults file or on the command line. The standard command line 
options of -fn and -font can also be used. The font unit value is taken as the QUAD_WIDTH 
property of the font The function XmSetFontUnits allows applications to specify the font unit 
values. 



RETURN VALUE 

Returns the converted value. 



ERRORS 

If a NULL widget, incorrect orientation, or incorrect unitjype is supplied as parameter data, 0 is 
returned. 



RELATED INFORMATION 

XmSetFontUnit(3X) 
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XmCreateArrowButton (3X) 



NAME 



XmCreateArrowButton - the ArrowButton widget creation function. 



SYNOPSIS 



#include <Xm/ArrowB.h> 



Widget XmCreateArrowButton (parent, name, arglist, argcouni) 



Widget parent; 
String name; 
ArgList arglist, 



Cardinal argcounf, 



DESCRIPTION 



XmCreateArrowButton creates an instance of an ArrowButton widget and returns the associated 



For a complete definition of ArrowButton and its associated resources, see XmArrowButton(3X). 

RETURN VALUE 

Returns the ArrowButton widget ID. 

RELATED INFORMATION 

XmArrowButton(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreateArrowButtonGadget (3X) 



NAME 

XmCreateArrowButtonGadget - the ArrowButtonGadget creation function. 

SYNOPSIS 

#include <Xm/ArrowB.h> 

Widget XmCreateArrowButtonGadget {parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist} 
Cardinal argcount; 

DESCRIPTION 

XmCreateArrowButtonGadget creates an instance of an ArrowButtonGadget widget and returns 
the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of ArrowButtonGadget and its associated resources, see 
XmArrowButtonGadget(3X) . 

RETURN VALUE 

Returns the ArrowButtonGadget widget ID. 

RELATED INFORMATION 

XmArrowButtonGadget(3X). 
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XmCreateBulktinBoard (3X) 



NAME 

XmCreateBulletinBoard - the BulletinBoard widget creation function. 



SYNOPSIS 

#include <Xm/BulletinB.h> 

Widget XmCreateBulletinBoard (parent, name, arglist, argcount) 

Widget parent, 

String name; 

ArgList arglist, 

Cardinal argcount, 



DESCRIPTION 

XmCreateBulletinBoard creates an instance of a BulletinBoard widget and returns the associated 
widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of BulletinBoard and its associated resources, see 
XmBuIletinBoard(3X). 



RETURN VALUE 

Returns the BulletinBoard widget ID. 



RELATED INFORMATION 

XmBuUetinBoard(3X). 
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XmCreateBulletinBoardDialog (3X) 



NAME 

XmCreateBulletinBoardDialog - the BulletinBoard BuIIetinBoardDialog convenience creation 
function. 



SYNOPSIS 

#include <Xm/BulletinB.h> 

Widget XmCreateBulletinBoardDialog (parent, name, arglist, argcouni) 
Widget parent, 
String name; 
ArgList arglisf, 
Cardinal argcount; 

DESCRIPTION 

XmCreateBulletinBoardDialog is a convenience creation function that creates a DialogShell and 
an unmanaged BulletinBoard child of the DialogShell. A BuIIetinBoardDialog is used for interac- 
tions not supported by the standard dialog set This function does not automatically create any 
labels, buttons, or other dialog components. Such components should be added by the application 
after the BuIIetinBoardDialog is created. 

Use XtManageChild to pop up the BuIIetinBoardDialog (passing the BulletinBoard as the widget 
parameter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of BulletinBoard and its associated resources, see 
XmBulletinBoard(3X). 



RETURN VALUE 

Returns the BulletinBoard widget ID. 

RELATED INFORMATION 

XmBuIletinBoard(3X). 
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XmCreateCascadeButton (3X) 



NAME 

XmCreateCascadeButton - the CascadeButton widget creation function. 

SYNOPSIS 

#include <Xm/CascadeB.h> 

Widget XmCreateCascadeButton (parent, name, arglist, argcount) 
Widget parent", 
String name, 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateCascadeButton creates an instance of a CascadeButton widget and returns the associ- 
ated widget ID. 

parent Specifies the parent widget ID. The parent must be a RowColumn widget. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of CascadeButton and its associated resources, see 
XmCascadeButton(3X). 

RETURN VALUE 

Returns the CascadeButton widget ID. 

RELATED INFORMATION 

XmCascadeButton(3X). 
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XmCreateCascadeButtonGadget (3X) 



NAME 

XmCreateCascadeButtonGadget - the CascadeButtonGadget creation function. 

SYNOPSIS 

#include <Xm/CascadeBG.h> 

Widget XmCreateCascadeButtonGadget {parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateCascadeButtonGadget creates an instance of a CascadeButtonGadget and returns the 
associated widget ID. 

parent Specifies the parent widget ID. The parent must be a RowColumn widget. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of CascadeButtonGadget and its associated resources, see 
XmCascadeButtonGadget(3X). 

RETURN VALUE 

Returns the CascadeButtonGadget widget ID. 

RELATED INFORMATION 

XmCascadeButtonGadget(3X). 
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NAME 

XmCreateCommand - the Command widget creation function. 

SYNOPSIS 

#include <Xm/Command.h> 

Widget XmCreateCommand (parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist, 
Cardinal argcount, 

DESCRIPTION 

XmCreateCommand creates an instance of a Command widget and returns the associated widget 
ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of Command and its associated resources, see XmCommand(3X). 

RETURN VALUE 

Returns the Command widget ID. 

RELATED INFORMATION 
XmCommand(3X). 
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NAME 



XmCreateDialogShell - the DialogShell widget creation function. 



SYNOPSIS 



#include <Xm/DialogS.h> 



Widget XmCreateDialogShell 



(parent, name, arglist, argcount) 



Widget 
String 
Arglist 
Cardinal 



parent; 
name, 
arglist; 



argcount; 



DESCRIPTION 



XmCreateDialogShell creates an instance of a DialogShell widget and returns the associated 



For a complete definition of DialogShell and its associated resources, see XmDialogShell(3X). 

RETURN VALUE 

Returns the DialogShell widget ID. 

RELATED INFORMATION 

XmDialogShell(3X). 
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widget ID. 



parent 



arglist 
argcount 



name 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreateDrawingArea (3X) 



NAME 



XmCreateDrawingArea - the DrawingArea widget creation function. 



SYNOPSIS 



#include <Xm/DrawingA.h> 



Widget XmCreateDrawingArea (parent, name, arglist, argcount) 




Cardinal argcount; 



DESCRIPTION 



XmCreateDrawingArea creates an instance of a DrawingArea widget and returns the associated 



For a complete definition of DrawingArea and its associated resources, see XmDrawingArea(3X). 

RETURN VALUE 

Returns the DrawingArea widget ID. 

RELATED INFORMATION 

XmDrawingArea(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreateDrawnButton (3X) 



NAME 



XmCreateDrawnButton - the DrawnButton widget creation function. 



SYNOPSIS 



#include <Xm/DrawnB.h> 



Widget XmCreateDrawnButton {parent, name, arglist, argcount) 



Widget parent, 
String name; 
ArgList arglist; 



Cardinal argcount; 



DESCRIPTION 



XmCreateDrawnButton creates an instance of a DrawnButton widget and returns the associated 



For a complete definition of DrawnButton and its associated resources, see XmDrawnButton(3X). 

RETURN VALUE 

Returns the DrawnButton widget ID. 

RELATED INFORMATION 

XmDrawnButton(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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NAME 

XmCreateErrorDialog - the MessageBox ErrorDialog convenience creation function. 

SYNOPSIS 

#include <Xm/MessageB.h> 

Widget XmCreateErrorDialog (parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist, 
Cardinal argcount; 

DESCRIPTION 

XmCreateErrorDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. An ErrorDialog warns the user of an invalid or 
potentially dangerous condition. It includes a symbol, a message, and three buttons. The default 
symbol is an octagon with a diagonal slash. The default button labels are OK, Cancel, and Help. 

Use XtManageChild to pop up the ErrorDialog (passing the MessageBox as the widget parame- 
ter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X). 
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NAME 

XmCreateFileSelectionBox - the FileSelectionBox widget creation function. 



SYNOPSIS 

#include <Xm/FUeSB.h> 



Widget XmCreateFileSelectionBox (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglisf, 
Cardinal argcount; 



DESCRIPTION 

XmCreateFileSelectionBox creates an unmanaged FileSelectionBox. A FileSelectionBox is used 
to select a file and includes the following: 

• An editable text field for the directory mask. 

• A scrolling list of file names. 

• An editable text field for the selected file. 

• Labels for the list and text fields. 

• Four buttons. 

The default button labels are OK, Filter, Cancel, and Help. One additional WorkArea child may 
be added to the FileSelectionBox after creation. 

If the parent of the FileSelectionBox is a DialogShell, use XtManageChild to pop up the 
FileSelectionDialog (passing the FileSelectionBox as the widget parameter); use XtUn- 
manageChild to pop it down. 



parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of FileSelectionBox and its associated resources, see 
XmFiIeSelectionBox(3X). 



RETURN VALUE 

Returns the FileSelectionBox widget ID. 



RELATED INFORMATION 

XmFileSelectionBox(3X). 



HISTORY/DIRECTION 

HP-UX Programs using FileSelectionBox must be linked with /lib/libPW.a. 
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NAME 

XmCreateFileSelectionDialog - the FUeSelectionBox FileSelectionDialog convenience creation 
function. 

SYNOPSIS 

#include <Xm/FileSB.h> 

Widget XmCreateFileSelectionDialog (parent, name, arglist, argcount) 
Widget parenf, 
String name; 
ArgList arglist, 
Cardinal argcount; 

DESCRIPTION 

XmCreateFileSelectionDialog is a convenience creation function that creates a DialogShell and an 
unmanaged FUeSelectionBox child of the DialogShell. A FileSelectionDialog selects a file. It 
includes the following: 

• An editable text field for the directory mask. 

• A scrolling list of filenames. 

• An editable text field for the selected file. 

• Labels for the list and text fields. 

• Four buttons. 

The default button labels are: OK, Filter, Cancel, and Help. One additional WorkArea child may 
be added to the FUeSelectionBox after creation. 

Use XtManageChild to pop up the FileSelectionDialog (passing the FUeSelectionBox as the 
widget parameter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of FUeSelectionBox and its associated resources, see 
XmFileSelectionBox(3X). 

RETURN VALUE 

Returns the FUeSelectionBox widget ID. 

RELATED INFORMATION 

XmFileSelectionBox(3X). 

HISTORY/DIRECTION 

HP-UX Programs using FUeSelectionBox must be linked with /lib/libPW.a. 
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NAME 

XmCreateForm - the Form widget creation function. 



SYNOPSIS 

#include <Xm/Form.h> 



Widget XmCreateForm (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreateForm creates an instance of a Form widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 
For a complete definition of Form and its associated resources, see XmForm(3X). 



RETURN VALUE 

Returns the Form widget ID. 



RELATED INFORMATION 
XmForm(3X). 
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NAME 

XmCreateFormDialog - a Form FormDialog convenience creation function. 

SYNOPSIS 

#include <Xm/Form.h> 

Widget XmCreateFormDialog (parent, name, arglist, argcount) 



DESCRIPTION 

XmCreateFormDialog is a convenience creation function that creates a DialogShell and an 
unmanaged Form child of the DialogShell. A FormDialog is used for interactions not supported 
by the standard dialog set. This function does not automatically create any labels, buttons, or 
other dialog components. Such components should be added by the application after the FormDi- 
alog is created. 

Use XtManageChild to pop up the FormDialog (passing the Form as the widget parameter); use 
XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of Form and its associated resources, see XmForm(3X). 

RETURN VALUE 

Returns the Form widget ID. 

RELATED INFORMATION 
XmForm(3X). 
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Widget 
String 
ArgList 
Cardinal 



parenf, 
name; 
arglist, 



argcount; 
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NAME 

XmCreateFrame - the Frame widget creation function. 



SYNOPSIS 

#include <Xm/Frame.h> 



Widget XmCreateFrame {parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreateFrame creates an instance of a Frame widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 
For a complete definition of Frame and its associated resources, see XmFrame(3X). 



RETURN VALUE 

Returns the Frame widget ID. 



RELATED INFORMATION 
XmFrame(3X). 
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NAME 

XmCreatelnformationDialog - the MessageBox InformationDialog convenience creation func- 
tion. 

SYNOPSIS 

#include < Xm /MessagcB.h > 

Widget XmCreatelnformationDialog (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglisf, 
Cardinal argcount; 

DESCRIPTION 

XmCreatelnformationDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. An InformationDialog gives the user informa- 
tion, such as the status of an action. It includes a symbol, a message, and three buttons. The 
default symbol is a lower case i. The default button labels are OK, Cancel, and Help. 

Use XtManageChild to pop up the InformationDialog (passing the MessageBox as the widget 
parameter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X). 
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NAME 

XmCreateLabel - the Label widget creation function. 

SYNOPSIS 

#include <Xm/LabeLh> 

Widget XmCreateLabel (parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateLabel creates an instance of a Label widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of Label and its associated resources, see XmLabel(3X). 

RETURN VALUE 

Returns the Label widget ID. 

RELATED INFORMATION 
XmLabel(3X). 
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NAME 



XmCreateLabelGadget - the LabelGadget creation function. 



SYNOPSIS 



#include <Xm/LabelG.h> 



Widget XmCreateLabelGadget (parent, name, arglist, argcount) 



Widget parent, 
String name, 
ArgList arglist, 



Cardinal argcount, 



DESCRIPTION 



XmCreateLabelGadget creates an instance of a LabelGadget widget and returns the associated 



For a complete definition of LabelGadget and its associated resources, see XmLabelGadget(3X). 

RETURN VALUE 

Returns the LabelGadget widget ID. 

RELATED INFORMATION 

XmLabelGadget(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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NAME 

XmCreateList - the List widget creation function. 



SYNOPSIS 

#include <Xm/List.h> 

Widget XmCreateList (parent, name, arglist, argcount)) 

Widget parents 

String name; 

Arglist arglisf, 

Cardinal argcount; 



DESCRIPTION 

XmCreateList creates an instance of a List widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 
For a complete definition of List and its associated resources, see XmList(3X). 



RETURN VALUE 

Returns the List widget ID. 



RELATED INFORMATION 
XmList(3X). 
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NAME 



XmCreateMainWindow - the MainWindow widget creation function. 



SYNOPSIS 



#include <Xm/MainW.h> 



Widget XmCreateMainWindow {parent, name, arglist, argcount) 




Cardinal argcount; 



DESCRIPTION 



XmCreateMainWindow creates an instance of a MainWindow widget and returns the associated 



For a complete definition of MainWindow and its associated resources, see XmMainWindow(3X). 

RETURN VALUE 

Returns the MainWindow widget ID. 

RELATED INFORMATION 

XmMainWindow(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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NAME 

XmCreateMenuBar - a RowColumn widget convenience creation function. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmCreateMenuBar {parent, name, arglist, argcouni) 
Widget parent; 
String name, 
ArgList arglist; 
Cardinal argcounf, 

DESCRIPTION 

XmCreateMenuBar creates an instance of a RowColumn widget of type XmMENUJBAR and 
returns the associated widget ID. 

It is provided as a convenience function for creating RowColumn widgets configured to operate as 
a MenuBar and is not implemented as a separate widget class. 

The MenuBar widget is generally used for building a Pulldown menu system. Typically, a Menu- 
Bar is created and placed along the top of the application window, and several CascadeButtons are 
inserted as the children. Each of the CascadeButtons has a Pulldown MenuPane associated with 
it. These Pulldown MenuPanes must have been created as children of the MenuBar. The user 
interacts with the MenuBar by using either the mouse or the keyboard. 

The MenuBar displays a 3-D shadow along its border. The application controls the shadow attri- 
butes using the visual-related resources supported by XmManager. 

The MenuBar widget is homogeneous in that it only accepts children which are a subclass of 
XmCascadeButton. Attempting to insert a child of a different class results in a warning message. 

If the MenuBar does not have enough room to fit all of its subwidgets on a single line, the Menu- 
Bar attempts to wrap the remaining entries onto additional lines if allowed by the geometry 
manager of the parent widget. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the RowColumn widget ID. 

RELATED INFORMATION 

XmCascadeButton(3X), XmCreatePulIdownMenu(3X), XmManager (3X), and 
XmRowColumn(3X). 
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NAME 

XmCreateMemiShell - the MenuShell widget creation function. 



SYNOPSIS 

#include <Xm/MenuSheIl.h> 

Widget XmCreateMemiShell (parent, name, arglist, argcount) 
Widget parent^ 
String name} 
ArgList arglist, 
Cardinal argcount; 



DESCRIPTION 

XmCreateMemiShell creates an instance of a MenuShell widget and returns the associated widget 
ID. 



parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MenuShell and its associated resources, see XmMenuSheIl(3X). 

RETURN VALUE 

Returns the MenuShell widget ID. 



RELATED INFORMATION 

XmMenuShell(3X). 
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NAME 

XmCreateMessageBox - the MessageBox widget creation function. 

SYNOPSIS 

#include <Xm/MessageB.h> 

Widget XmCreateMessageBox (parent, name, arglist, argcount) 

Widget parent; 

String name; 

ArgList arglist; 

Cardinal argcount; 



DESCRIPTION 

XmCreateMessageBox creates an unmanaged MessageBox. A MessageBox is used for common 
interaction tasks, which include giving information, asking questions, and reporting errors. It 
includes the following: 

• An optional symbol. 

• A message. 

• Three buttons. 

By default, there is no symbol. The default button labels are OK, Cancel, and Help. 

If the parent of the MessageBox is a Dialogshell, use XtManageChild to pop up the MessageBox 
(passing the MessageBox as the widget parameter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 



RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X) . 
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NAME 

XmCreateMessageDialog - the MessageBox MessageDialog convenience creation function. 

SYNOPSIS 

#include <Xm/MessageB.h> 

Widget XmCreateMessageDialog (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateMessageDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. A MessageDialog is used for common interac- 
tion tasks, which include giving information, asking questions, and reporting errors. It includes a 
symbol, a message, and three buttons. By default, there is no symbol. The default button labels 
are OK, Cancel, and Help. 

Use XtManageChild to pop up the MessageDialog (passing the MessageBox as the widget param- 
eter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the MessageBox widget ID. 



RELATED INFORMATION 

XmMessageBox(3X) . 
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NAME 

XmCreateOptionMenu - a RowCoIumn widget convenience creation function. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmCreateOptionMenu (parent, name, arglist, argcount) 
Widget parenf, 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateOptionMenu creates an instance of a RowCoIumn widget of type XmMENU_OPTION 
and returns the associated widget ID. 

It is provided as a convenience function for creating a RowCoIumn widget configured to operate 
as an OptionMenu and is not implemented as a separate widget class. 

The OptionMenu widget is a specialized RowCoIumn manager composed of a label, a selection 
area, and a single Pulldown MenuPane. When an application creates an OptionMenu widget, it 
supplies the label string and the Pulldown MenuPane. In order to succeed, there must be a valid 
XmNsubMenuId resource set when calling this function. When the OptionMenu is created, the 
Pulldown MenuPane must have been created as a child of the OptionMenu's parent and must be 
specified. The LabelGadget and the selection area (a CascadeButtonGadget) are created by the 
OptionMenu. 

An OptionMenu is laid out with the label displayed on the left side of the widget and the selection 
area on the right side. The selection area has a dual purpose; it displays the label of the last item 
selected from the associated Pulldown MenuPane, and it provides the means for posting the Pull- 
down MenuPane. 

The OptionMenu typically does not display any 3-D visuals around itself or the internal Label- 
Gadget. By default, the internal CascadeButtonGadget has a visible 3-D shadow. The application 
may change this by getting the CascadeButtonGadget ID using XmOptionButtonGadget and then 
calling XtSetValues using the standard visual-related resources. 

The Pulldown MenuPane is posted by moving the mouse pointer over the selection area and 
pressing the mouse button defined by OptionMenu's XmNwhichButton resource. The Pulldown 
MenuPane is posted and positioned such that the last selected item is directly over the selection 
area. The mouse is then used to arm the desired menu item. When the mouse button is released, 
the armed menu item is selected and the label within the selection area is changed to match that of 
the selected item. By default, mouse button 1 is used to interact with an OptionMenu. The 
default can be changed via the RowCoIumn resource XmNwhichButton. 

The OptionMenu also operates by using the keyboard interface mechanism. If the application has 
established a mnemonic with the OptionMenu, typing the mnemonic causes the Pulldown Menu- 
Pane to be posted with traversal enabled. The standard traversal keys can then be used to move 
within the MenuPane. Selection can occur as the result of pressing the Return key or typing a 
mnemonic or accelerator for one of the menu items. 

An application may use the XmNmenuHistory resource to indicate which item in the Pulldown 
MenuPane should be treated as the current choice and have its label displayed in the selection 
area. By default, the first item in the Pulldown MenuPane is used. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 
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XmCreateOptionMenu (3X) 



argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the RowColumn widget ID. 

RELATED INFORMATION 

XmCascadeButtonGadget(3X), XmCreatePulIdownMenu(3X), XmLabelGadget(3X), and 
XmRowColumn(3X). 
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NAME 

XmCreatePanedWindow - the PanedWindow widget creation function. 



SYNOPSIS 

#include <Xm/PanedW.h> 

Widget XmCreatePanedWindow (parent, name, arglist, argcount) 

Widget parent, 

String name; 

ArgList arglist; 

Cardinal argcount; 



DESCRIPTION 

XmCreatePanedWindow creates an instance of a PanedWindow widget and returns the associated 
widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of PanedWindow and its associated resources, see 
XmPanedWindow(3X). 



RETURN VALUE 

Returns the PanedWindow widget ID. 



RELATED INFORMATION 

XmPanedWindow(3X). 
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NAME 

XmCreatePopupMenu - a RowColumn widget convenience creation function. 



SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmCreatePopupMenu (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreatePopupMenu creates an instance of a RowColumn widget of type XmMENU POPUP 
and returns the associated widget ID. When using this function to create the Popup Menupane, a 
MenuShell widget is automatically created as the parent of the MenuPane. The parent of the 
MenuShell widget is the widget indicated by the parent parameter. 

XmCreatePopupMenu is provided as a convenience function for creating RowColumn widgets 
configured to operate as Popup MenuPanes and is not implemented as a separate widget class. 

The PopupMenu is used as the first MenuPane within a PopupMenu system; all other MenuPanes 
are of the Pulldown type. A Popup MenuPane displays a 3-D shadow, unless the feature is dis- 
abled by the application. The shadow appears around the edge of the MenuPane. 

The Popup MenuPane must be created as the child of a MenuShell widget in order to function 
properly when it is incorporated into a menu. If the application uses this convenience function for 
creating a Popup MenuPane, then the MenuShell is automatically created as the real parent of the 
MenuPane. If the application does not use this convenience function to create the RowColumn to 
function as a Popup Menupane, then it is the application's responsibility to create the MenuShell 
widget. 

To access the PopupMenu, the application must first position the widget using the XmMenuPosi- 
tion function and then manage it using XtManageChild. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 



For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 



RETURN VALUE 

Returns the RowColumn widget ID. 



RELATED INFORMATION 

XmMenuPosition(3X), XmMenuShell(3X), and XmRowColumn(3X). 
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NAME 

XmCreatePromptDialog - the SelectionBox PromptDialog convenience creation function. 

SYNOPSIS 

#include <Xm/SelectioB.h> 

Widget XmCreatePromptDialog {parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreatePromptDialog is a convenience creation function that creates a DialogShell and an 
unmanaged SelectionBox child of the DialogShell. A PromptDialog prompts the user for text 
input It includes a message, a text input region, and three managed buttons. The default button 
labels are OK, Cancel, and Help. An additional button, with Apply as the default label, is created 
unmanaged; it may be explicitly managed if needed. One additional WorkArea child may be 
added to the SelectionBox after creation. 

Use XtManageChild to pop up the PromptDialog (passing the SelectionBox as the widget param- 
eter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of SelectionBox and its associated resources, see XmSeIectionBox(3X). 

RETURN VALUE 

Returns the SelectionBox widget ID. 

RELATED INFORMATION 

XmSelectionBox(3X) . 
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NAME 



XmCreatePulldownMenu - a RowColumn widget convenience creation function. 



SYNOPSIS 



#inciude <Xm/RowColumn.h> 



Widget XmCreatePulldownMenu (parent, name, arglist, argcount) 



Widget parent; 
String name; 
ArgList arglist; 



Cardinal argcount; 



DESCRIPTION 



XmCreatePulldownMenu creates an instance of a RowColumn widget of type 
XmMENU PULLDOWN and returns the associated widget ID. When using this function to 
create the Pulldown MenuPane, a MenuShell widget is automatically created as the parent of the 
MenuPane. If the widget specified by the parent parameter is a Popup or a Pulldown MenuPane, 
then the MenuShell widget is created as a child of the parent's MenuShell; otherwise, it is created 
as a child of the specified parent widget. 

XmCreatePulldownMenu is provided as a convenience function for creating RowColumn widgets 
configured to operate as Pulldown MenuPanes and is not implemented as a separate widget class. 

A Pulldown MenuPane displays a 3-D shadow, unless the feature is disabled by the application. 
The shadow appears around the edge of the MenuPane. 

A Pulldown MenuPane is used when creating submenus that are to be attached to a CascadeBut- 
ton or a CascadeButtonGadget. This is the case for all MenuPanes that are part of a Pulldown- 
Menu system (a MenuBar), the MenuPane associated with an OptionMenu, and any MenuPanes 
that cascade from a Popup MenuPane. Pulldown MenuPanes, which are to be associated with an 
OptionMenu, must be created before the OptionMenu is created. 

The Pulldown MenuPane must be attached to a CascadeButton or CascadeButtonGadget which 
resides in a MenuBar, a Popup MenuPane, a Pulldown MenuPane, or an OptionMenu. This is 
done by using the button resource XmNsubMenuId. 

A MenuShell widget is required between the Pulldown MenuPane and its parent. If the applica- 
tion uses this convenience function for creating a Pulldown MenuPane, then the MenuShell is 
automatically created as the real parent of the MenuPane; otherwise, it is the application's respon- 
sibility to create the MenuShell widget. 

To function correctly when incorporated into a menu, the Pulldown MenuPane's hierarchy must 
be considered; this hierarchy is dependent upon the type of menu system that is being built: 

• If the Pulldown MenuPane is to be pulled down from a MenuBar, its parent must be the Menu- 



• If the Pulldown MenuPane is to be pulled down from a Popup or another Pulldown Menu- 
Pane, its parent must be that Popup or Pulldown MenuPane. 

• If the Pulldown MenuPane is to be pulled down from an OptionMenu, its parent must be the 
same as the OptionMenu parent. 



For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 



Bar. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreatePulldownMenu (3X) 



RETURN VALUE 

Returns the RowColumn widget ID. 

RELATED INFORMATION 

XmCascadeButton(3X), XmCascadeButtonGadget(3X), XmCreateOptionMenu(3X), 
XmCreatePopupMenu(3X), XmCreatePulldownMenu(3X), XmMenuShelI(3X), and 
XmRowCoIumn(3X). 
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NAME 



XmCreatePushButton - the PushButton widget creation function. 



SYNOPSIS 



#include <Xm/PushB.h> 



Widget XmCreatePushButton 



(parent, name, arglist, argcount) 



Widget 
String 
ArgList 
Cardinal 



parent; 
name; 
arglist; 



argcount; 



DESCRIPTION 



XmCreatePushButton creates an instance of a PushButton widget and returns the associated 



For a complete definition of PushButton and its associated resources, see XmPushButton(3X). 

RETURN VALUE 

Returns the PushButton widget ID. 

RELATED INFORMATION 

XmPushButton(3X). 
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widget ID. 



parent 



arglist 
argcount 



name 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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NAME 

XmCreatePushButtonGadget - the PushButtonGadget creation function. 

SYNOPSIS 

#include <Xm/PushBG.h> 

Widget XmCreatePushButtonGadget (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreatePushButtonGadget creates an instance of a PushButtonGadget widget and returns the 
associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of PushButtonGadget and its associated resources, see 
XmPushButtonGadget(3X). 

RETURN VALUE 

Returns the PushButtonGadget widget ID. 

RELATED INFORMATION 

XmPushButtonGadget(3X). 
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NAME 

XmCreateQuestionDialog - the MessageBox QuestionDialog convenience creation function. 

SYNOPSIS 

#include <Xm/MessageB.h> 

Widget XmCreateQuestionDialog (parent, name, arglist, argcount) 
Widget parent; 
String name, 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateQuestionDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. A QuestionDialog is used to get the answer to 
a question from the user. It includes a symbol, a message, and three buttons. The default symbol 
is a question mark. The default button labels are OK, Cancel, and Help. 

Use XtManageChild to pop up the QuestionDialog (passing the MessageBox as the widget 
parameter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X) . 
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NAME 

XmCreateRadioBox - a RowColumn widget convenience creation function. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmCreateRadioBox (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateRadioBox creates an instance of a RowColumn widget of type XmWORK_AREA and 
returns the associated widget ID. Topically, this is a composite widget that contains multiple Tog- 
gleButtonGadgets. The RadioBox arbitrates and ensures that at most one ToggleButtonGadget is 
on at any given time. 

The ToggleButtons are forced to have the resources XmNindicatorType set to 
XmONE OF MANY and XmNvisibleWhenOff set to True. 

It is provided as a convenience function for creating RowColumn widgets. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the RowColumn widget ID. 

RELATED INFORMATION 

XmRowCoIumn(3X). 
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NAME 



XmCreateRowColumn - the RowColumn widget creation function. 



SYNOPSIS 



#include <Xm/RowColumn.h> 



Widget XmCreateRowColumn 



(parent, name, arglist, argcouni) 



Widget 
String 
ArgList 



parent; 
name; 
arglist; 



Cardinal 



argcounf, 



DESCRIPTION 

XmCreateRowColumn creates an instance of a RowColumn widget and returns the associated 
widget ID. If XmNrowColumnType is not specified, then it is created with XmWORK_AREA, 
which is the default 

If this function is used to create a Popup Menu of type XmMENU_POPUP or a Pulldown Menu of 
type XmMENU_PULLDOWN, a MenuShell widget is not automatically created as the parent of 
the MenuPane. "The application must first create the MenuShell by using either XmCreateMenu- 
Shell or the standard toolkit create function. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the RowColumn widget ID. 

RELATED INFORMATION 

XmCreateMenuShell(3X), XmCreatePopupMenu(3X), XmCreatePulldownMenu(3X), and 
XmRowColumn(3X). 
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NAME 

XmCreateScale - the Scale widget creation function. 



SYNOPSIS 

#include <Xm/ScaIe.h> 

Widget XmCreateScale {parent, name, arglist, argcount) 

Widget parent; 

String name, 

ArgList arglisf, 

Cardinal argcount; 



DESCRIPTION 

XmCreateScale creates an instance of a Scale widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 
For a complete definition of Scale and its associated resources, see XmScale(3X). 



RETURN VALUE 

Returns the Scale widget ID. 



RELATED INFORMATION 
XmScale(3X). 
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NAME 

XmCreateScrollBar - the ScrollBar widget creation function. 



SYNOPSIS 

#include <Xm/ScrollBar.h> 



Widget XmCreateScrollBar (parent, name, arglist, argcount) 
Widget parent; 
String name\ 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreateScrollBar creates an instance of a ScrollBar widget and returns the associated widget 
ID. 



parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of ScrollBar and its associated resources, see XmScrollBar(3X). 

RETURN VALUE 

Returns the ScrollBar widget ID. 



RELATED INFORMATION 
XmScroUBar(3X). 
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NAME 

XmCreateScrolledList - the List ScrolledList convenience creation function. 



SYNOPSIS 

#include <Xm/List.h> 



Widget XmCreateScrolledList (parent, name, arglist, argcount)) 

Widget parent, 

String name; 

ArgList arglist; 

Cardinal argcounf, 



DESCRIPTION 

XmCreateScrolledList creates an instance of a List widget that is contained within a ScrolledWin- 
dow. All ScrolledWindow subarea widgets are automatically created by this function. The ID 
returned by this function is that of the List widget. Use this ID for all normal List operations, as 
well as those that are relevant for the ScrolledList widget. 

Other aspects of the appearance and behavior of the ScrolledList should be controlled by using 
the ScrolledWindow widget resources. For instance, if an application writer wishes to specify the 
xy location of a ScrolledList within a larger manager, set the XmNx and XmNy resources of the 
ScrolledWindow rather than of the List widget. 

To obtain the ID of the ScrolledWindow widget associated with the ScrolledList, use the Xt Intrin- 
sics XtParent function. The name of the ScrolledWindow created by this function is formed by 
concatenating the letters SW onto the end of the name specified in the parameter list. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 



For a complete definition of List and its associated resources, see XmList(3X). 



RETURN VALUE 

Returns the List widget ID. 



RELATED INFORMATION 

XmList(3X) and XmScrolledWindow(3X). 
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XmCreateScrolledText (3X) 



NAME 

XmCreateScrolledText - the Text ScrolledText convenience creation function. 



SYNOPSIS 

# include <Xm/Text.h> 

Widget XmCreateScrolledText (parent, name, arglist, argcount) 
Widget parent; 
String name, 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateScrolledText creates an instance of a Text widget that is contained within a ScrolledWin- 
dow. All ScrolledWindow subarea widgets are automatically created by this function. The ID 
returned by this function is that of the Text widget. Use this ID for all normal Text operations, as 
well as those that are relevant for the ScrolledText widget. 

The Text widget defaults to single-line text edit; therefore, no ScrollBars are displayed. The Text 
resource XmNeditMode must be set to XmMULTI-LINE-EDIT to display the ScrollBars. 

Other aspects of the appearance and behavior of the ScrolledText should be controlled by using 
the ScrolledWindow widget resources. For instance, if an application writer wishes to specify the 
xy location of a ScrolledText within a larger manager, set the XmNx and XmNy resources of the 
ScrolledWindow rather than of the Text widget. 

To obtain the ID of the ScrolledWindow widget associated with the ScrolledText, use the Xt 
Intrinsics XtParent function. The name of the ScrolledWindow created by this function is formed 
by concatenating the letters SW onto the end of the name specified in the parameter list. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of Text and its associated resources, see XmText(3X). 

RETURN VALUE 

Returns the Text widget ID. 

RELATED INFORMATION 

XmScrolledWindow(3X) and XmText(3X). 
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NAME 

XmCreateScrolledWindow - the ScrolIedWindow widget creation function. 



SYNOPSIS 

#include <Xm/ScroUedW.h> 

Widget XmCreateScrolledWindow (parent, name, arglist, argcount) 
Widget parent, 
String name; 
ArgList arglist, 
Cardinal argcount, 



DESCRIPTION 

XmCreateScrolledWindow creates an instance of a ScrolIedWindow widget and returns the associ- 
ated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of ScrolIedWindow and its associated resources, see 
XmScrolIedWindow(3X). 



RETURN VALUE 

Returns the ScrolIedWindow widget ID. 



RELATED INFORMATION 

XmScrolIedWindow(3X) . 
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NAME 

XmCreateSelectionBox - the SelectionBox widget creation function. 

SYNOPSIS 

#include <Xm/SelectioB.h> 

Widget XmCreateSelectionBox (parent, name, arglist, argcouni) 



DESCRIPTION 

XmCreateSelectionBox creates an unmanaged SelectionBox. A SelectionBox is used to get a selec- 
tion from a list of alternatives from the user and includes the following: 

• A scrolling list of alternatives. 

• An editable text field for the selected alternative. 

• Labels for the list and text field. 

• Three buttons. 

The default button labels are OK, Cancel, and Help. An Apply button is created unmanaged and 
may be explicitly managed as needed. One additional WorkArea child may be added to the Selec- 
tionBox after creation. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of SelectionBox and its associated resources, see XmSelectionBox(3X). 

RETURN VALUE 

Returns the SelectionBox widget ID. 

RELATED INFORMATION 

XmSelectionBox(3X) 
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Widget 
String 
ArgList 
Cardinal 



parent; 
name; 
arglist; 



argcount, 
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XmCreateSelectionDialog (3X) 



NAME 

XmCreateSelectionDialog - the SelectionBox SelectionDialog convenience creation function. 



SYNOPSIS 

#include <Xm/SelectioB.h> 



Widget XmCreateSelectionDialog (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreateSelectionDialog is a convenience creation function that creates a DialogShell and an 
unmanaged SelectionBox child of the DialogShell. A SelectionDialog offers the user a choice from 
a list of alternatives and gets a selection. It includes the following: 

• A scrolling list of alternatives. 

• An editable text field for the selected alternative. 

• Labels for the text field. 

• Three buttons. 

The default button labels are OK, Cancel, and Help. One additional WorkArea child may be 
added to the SelectionBox after creation. 

Use XtManageChild to pop up the SelectionDialog (passing the SelectionBox as the widget 
parameter); use XtUnmanageChild to pop it down. 



parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of SelectionBox and its associated resources, see XmSeIectionBox(3X). 



RETURN VALUE 

Returns the SelectionBox widget ID. 



RELATED INFORMATION 

XmSelectionBox(3X). 
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Xm Create Separator (3X) 



NAME 



XmCreateSeparator - the Separator widget creation function. 



SYNOPSIS 



#include <Xm/Separator.h> 



Widget XmCreateSeparator (parent, name, arglist, argcount) 



Widget parent; 
String name; 
ArgList arglist; 



Cardinal argcount; 



DESCRIPTION 



XmCreateSeparator creates an instance of a Separator widget and returns the associated widget 



For a complete definition of Separator and its associated resources, see XmSeparator(3X). 

RETURN VALUE 

Returns the Separator widget ID. 

RELATED INFORMATION 
XmSeparator (3X) . 



Hewlett-Packard Company - 1 - Jul 27, 1989 



ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget. 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreateSeparatorGadget (3X) 



NAME 

XmCreateSeparatorGadget - the SeparatorGadget creation function. 

SYNOPSIS 

#include <Xm/SeparatoG.h> 

Widget XmCreateSeparatorGadget (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateSeparatorGadget creates an instance of a SeparatorGadget widget and returns the asso- 
ciated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of SeparatorGadget and its associated resources, see 
XmSeparatorGadget(3X). 

RETURN VALUE 

Returns the SeparatorGadget widget ID. 

RELATED INFORMATION 

XmSeparatorGadget(3X). 
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NAME 

XmCreateText - the Text widget creation function. 

SYNOPSIS 

#include <Xm/Text.h> 

Widget XmCreateText (parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateText creates an instance of a Text widget and returns the associated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of Text and its associated resources, see XmText(3X). 

RETURN VALUE 

Returns the Text widget ID. 

RELATED INFORMATION 
XmText(3X). 
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XmCreateToggleButton (3X) 



NAME 



XmCreateToggleButton - the ToggleButton widget creation function. 



SYNOPSIS 



#include <Xm/ToggleB.h> 



Widget XmCreateToggleButton (parent, name, arglist, argcount) 



Widget parent; 
String name; 
ArgList arglist; 



Cardinal argcount; 



DESCRIPTION 



XmCreateToggleButton creates an instance of a ToggleButton widget and returns the associated 



For a complete definition of ToggleButton and its associated resources, see XmToggleButton(3X). 

RETURN VALUE 

Returns the ToggleButton widget ID. 

RELATED INFORMATION 

XmToggleButton(3X). 
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widget ID. 



parent 



name 



arglist 
argcount 



Specifies the parent widget ID. 
Specifies the name of the created widget 
Specifies the argument list. 

Specifies the number of attribute/value pairs in the argument list (arglist). 
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XmCreateToggleButtonGadget (3X) 



NAME 

XmCreateToggleButtonGadget - the ToggleButtonGadget creation function. 

SYNOPSIS 

#include <Xm/ToggleBG.h> 

Widget XmCreateToggleButtonGadget (parent, name, arglist, argcount) 
Widget parent; 
String name, 
ArgList arglist; 
Cardinal argcount; 

DESCRIPTION 

XmCreateToggleButtonGadget creates an instance of a ToggleButtonGadget and returns the asso- 
ciated widget ID. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of ToggleButtonGadget and its associated resources, see 
XmToggleButtonGadget(3X). 

RETURN VALUE 

Returns the ToggleButtonGadget widget ID. 

RELATED INFORMATION 

XmToggleButtonGadget(3X). 
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XmCreateWarningDialog (3X) 



NAME 

XmCreateWarningDialog - a MessageBox WarningDialog convenience creation function. 



SYNOPSIS 

#include <Xm/MessageB.h> 



Widget XmCreateWarningDialog (parent, name, arglist, argcount) 
Widget parent; 
String name} 
ArgList arglist; 
Cardinal argcount; 



DESCRIPTION 

XmCreateWarningDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. A WarningDialog warns the user of action 
consequences and gives the user a choice of resolutions. It includes a symbol, a message, and 
three buttons. The default symbol is an exclamation point. The default button labels are OK, 
Cancel, and Help. 

Use XtManageChild to pop up the WarningDialog (passing the MessageBox as the widget param- 
eter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 



For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 



RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X) . 
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NAME 

XmCreateWorkingDialog - the MessageBox WorkingDialog convenience creation function. 

SYNOPSIS 

#include <Xm/MessageB.h> 

Widget XmCreateWorkingDialog {parent, name, arglist, argcount) 
Widget parent; 
String name; 
ArgList arglist, 
Cardinal argcount; 

DESCRIPTION 

XmCreateWorkingDialog is a convenience creation function that creates a DialogShell and an 
unmanaged MessageBox child of the DialogShell. A WorkingDialog informs the user that there is 
a time-consuming operation in progress and gives the user the ability to cancel the operation. It 
includes a symbol, a message, and three buttons. The default symbol is an hourglass. The default 
button labels are OK, Cancel, and Help. 

Use XtManageChild to pop up the WorkingDialog (passing the MessageBox as the widget param- 
eter); use XtUnmanageChild to pop it down. 

parent Specifies the parent widget ID. 

name Specifies the name of the created widget. 

arglist Specifies the argument list. 

argcount Specifies the number of attribute/value pairs in the argument list (arglist). 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the MessageBox widget ID. 

RELATED INFORMATION 

XmMessageBox(3X) . 
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XmCvtStringToUnitType (3X) 



NAME 

XmCvtStringToUnitType - a function that converts a string to a unit-type value. 



SYNOPSIS 

#include <Xm/Xm.h> 



void XmCvtStringToUnitType (orgs, num_args, fromycU, toyal) 
XrmValuePtr args\ 
Cardinal * num_args; 

XrmValue * fromyal; 

XrmValue * to val; 



DESCRIPTION 

XmCvtStringToUnitType converts a string to a unit type. Refer to man pages for XmGadget, 
XmManager, or XmPrimitive for a description of the valid unit types. 

Install this function as a resource converter using the Xt Intrinsics function XtAddConverter, 
rather than calling it directly. The following code segment shows how to install the converter into 
the toolkit's converter cache that will allow the resource XmNunitType to be specified through a 
resource file. 



XtAddConverter (XmRString, XmRUnitType, XmCvtStringToUnitType, NULL, 0); 



This function should only be installed by applications which need to allow the unit type resource 
to be specified through a resource file. It must be installed before any widget is created that is to 
have its XmNunitType resource set by data in a resource file. 



orgs Specifies a list of additional XrmValue arguments to the converter if additional 

context is needed to perform the conversion. For example, the string-to-font con- 
verter needs the widget's screen, or the string-to-pixel converter needs the widget's 
screen and color map. This argument if often NULL. 

numjtrp Specifies the number of additional XrmValue arguments. This argument is often 
zero. 

fromyal Specifies the value to convert. 

toyed Specifies the descriptor to use to return the converted value. 



RELATED INFORMATION 

XmGadget(3X), XmManager (3X), and XmPrimitive(3X). 
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XmDeactivateProtocol (3X) 



NAME 

XmDeactivateProtocol - a VendorShell function that deactivates a protocol without removing it. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/ProtocoIs.h> 

void XmDeactivateProtocol (shell, property, protocol) 
Widget shell; 
Atom property; 
Atom protocol; 

void XmDeactivateWMProtocol {shell, protocol) 
Widget shell; 
Atom protocol; 

DESCRIPTION 

XmDeactivateProtocol deactivates a protocol without removing it. It updates the handlers and the 
property, if the shell is realized. It is sometimes useful to allow a protocol's state information (call- 
back lists, etc.) to persist, even though the client may choose to temporarily resign from the 
interaction. The main use of this capability is to gray/ungray f.send msg entries in the Mwm sys- 
tem menu. This is supported by allowing a protocol to be in one of two states: active or inactive. 
If the protocol is active and the shell is realized, then the property will contain the protocol Atom. If 
the protocol is inactive, the Atom will not be present in the property. 

XmDeactivateWMProtocol is a convenience interface. It calls XmDeactivateProtocol with the pro- 
perty value set to the atom returned by interning WM PROTOC OLS . 

shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocol Specifies the protocol atom (or an int cast to Atom). 

For a complete definition of VendorShell and its associated resources, see Vendor Shell (3X). 

RELATED INFORMATION 

mwm(lX), VendorShell(3X), XmDeactivateWMProtocoI(3X), and XmInternAtom(3X). 
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XmDeactivateWMProtocol(3X) 



NAME 

XmDeactivateWMProtocol - a VendorShell convenience interface that deactivates a protocol 
without removing it. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmDeactivateWMProtocol {shell, protocol) 
Widget shell-, 
Atom protocol; 

DESCRIPTION 

XmDeactivateWMProtocol is a convenience interface. It calls XmDeactivateProtocol with the pro- 
perty value set to the atom returned by interning WM_PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocol Specifies the protocol atom (or an int cast to Atom). 

For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShelI(3X), XmDeactivateProtocol(3X), and XmInternAtom(3X). 
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XmDestroyPixmap (3X) 



NAME 

XmDestroyPixmap - a pixmap caching function that removes a pixmap from the pixmap cache. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmDestroyPixmap (screen, pixmap) 
Screen * screen; 

Pixmap pixmap; 

DESCRIPTION 

XmDestroyPixmap removes pixmaps that are no longer used. Pixmaps will only be completely 
freed when there is no further references to them. 

screen Specifies the display screen for which the pixmap was requested. 

pixmap Specifies the pixmap to be destroyed. 

RETURN VALUE 

Returns True when successful; returns False if there is no matching screen and pixmap in the pix- 
map cache. 

RELATED INFORMATION 

XmInstaIlImage(3X), XmUninstaIlImage(3X), and XmGetPixmap(3X). 
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NAME 

XmDialogShell - the DialogShell widget class. 

SYNOPSIS 

#include <Xm/DialogS.h> 

DESCRIPTION 

Modal and modeless dialogs use DialogShell as the Shell parent. DialogShell widgets cannot be 
iconified. Instead, all secondary DialogShell widgets associated with a primary MainShell widget 
are iconified and de-iconified as a group with the primary widget. 

The client indirectly manipulates DialogShell via the convenience interfaces during creation, and it 
can directly manipulate its BulletinBoard derived child. Much of the functionality of DialogShell 
assumes its child is a BulletinBoard subclass, although it can potentially stand alone. 

Classes 

DialogShell inherits behavior and resources from Core, Composite, Shell, WMShell, Ven- 
dorShell, and TransientShell classes. 

The class pointer is xmDialogShellWidgetClass. 

The class name is XmDialogShell. 

New Resources 

DialogShell defines no new resources, but overrides the XmNdeleteResponse resource in the 
VendorShell class. 

Inherited Resources 

DialogShell inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



TransientShell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNsaveUnder 


XmCSavellnder 


Boolean 


True 


CSG 


XmNtransient 


XmCTransient 


Boolean 


True 


CSG 



VendorShell Resource Set 


Name 


Class 


Type 


Default 

XmUNMAP 


Access 
CSG 


XmNdeleteResponse 


XmCDeleteResponse 


unsigned char 


XmNkeyboardFocusPolicy 


XmCKeyboardFocusPolky 


unsigned char 


XmEXPLIOT 


CSG 


XmNmwmDecorations 


XmCMwmDecorat ions 


int 


-1 


CSG 


XmNmwmFunctions 


XmCMwmFunctions 


int 


-1 


CSG 


XmNmwmlnputMode 


XmCMwmlnputMode 


int 


-1 


CSG 


XmNmwmMenu 


XmCMwmMenu 


String 


NULL 


CSG 


XmNshellUnitType 


XmCShellUnitType 


unsigned char 


XmPIXELS 


CSG 



Hewlett-Packard Company 



-1- 



Jul 27, 1989 



XmDialogShell(3X) 



XmDiak)gSheU(3X) 



WMShell Resource Set 


Name 




Type 


Default 


Access 


XmNheightlnc 


XmCHeightlnc 


int 


-1 


CSG 


XmNiconMask 


XmCIconMask 


Pixmap 


NULL 


CSG 


XmNiconPixmap 


XmCIconPixmap 


Pixmap 


NULL 


CSG 


XmNiconWindcw 


XmQconWindow 


Window 


NULL 


CSG 


XmNiconX 


XmCIconX 


int 




CSG 


XmNiconY 


XmCIconY 


int 




CSG 


XmNinitialSlate 


XmCInitialState 


int 




CSG 


XniN input 


XmCInput 


Boolean 


— 

True 


CSG 


AmN maxAspectX 


XmCMaxAspectX 


int 




CSG 


XmNmaxAspectY 




int 


— 


CSG 


XmNm&xHcight 


Vn^U«vU«i ntit 


int 


— 


CSG 


AniJN maxwiatn 


AJUCMaxWldta 


int 


— 


CSG 


AmN minAspectA 


XinCMinAspectX 


int 


— 


CSG 


abin minAspect Y 


XmCMinAspectY 


int 


— 


CSG 


XmNminHeight 


XmCMinHeight 


int 


_1 


CSG 


AJniN nun wiatu 


A mciviin w lot n 


int 




CSG 


XmNtitle 


XmCTitle 


char * 


NULL 


CSG 


XmNtransient 


XtnCTransient 


Boolean 


False 


CSG 


XmNwaitForWm 


XmCWaitForWm 


Boolean 


True 


CSG 


XmNwidthlnc 


XmCWidthlnc 


int 


-1 


CSG 


XmNwindosvGroup 


XmCWindowGroup 


XID 


None 


CSG 


XmNwnfTimeout 


XmCWiriTimeout 


int 


fivesecond 


CSG 



Shell Resource Set 


Name 


Class 


Type 


Default 

False 


Access 
CSG 


XmNallowShellResize 


XmCAUowShellResize 


Boolean 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNgeometry 


XmCGeometry 


String 


NULL 


CSG 


XinNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


False 


CSG 


XmNpopdownCallback 


XmCCallbadc 


XtCallbackList 


NULL 


C 


XmNpopupCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


False 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XinNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolonnap 


XmCColormap 


Colormap 


ShellColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



RELATED INFORMATION 

Composite(3X), Core(3X), Shell(3X), TransientShell(3X), VendorShell(3X), WMSheU(3X), and 
XmCreateDialogShell(3X). 
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NAME 

XmDrawingArea - the DrawingArea widget class. 

SYNOPSIS 

#include <Xm/DrawingA.h> 

DESCRIPTION 

DrawingArea is an empty widget that is easily adaptable to a variety of purposes. It does no draw- 
ing and defines no behavior except for invoking callbacks. Callbacks notify the application when 
graphics need to be drawn (exposure events or widget resize) and when the widget receives input 
from the keyboard or mouse. Applications are responsible for defining appearance and behavior 
as needed in response to DrawingArea callbacks. 

DrawingArea is also a composite widget and subclass of XmManager that supports minimal 
geometry management for multiple widget or gadget children. 

Classes 

DrawingArea inherits behavior and resources from the Core, Composite, Constraint, and 
XmManager classes. 

The class pointer is xmDrawingAreaWidgetClass. 
The class name is XmDrawingArea. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmDrawingArea Resource Set 


Name 


Class 


1>pe 


Default 


Access 


XmNexposeCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNinput Callback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


10 


CSG 


XmNresizeCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZE ANY 


CSG 



XmNexposeCallback 

Specifies the list of callbacks that is called when DrawingArea receives an exposure 
event. The callback reason is XmCR_EXPOSE. The callback structure also 
includes the exposure event. 

XmNinputCallback 

Specifies the list of callbacks that is called when the DrawingArea receives a key- 
board or mouse event (key or button, up or down). The callback reason is 
XmCR_INPUT. The callback structure also includes the input event. 

XmNmarginHeight 

Specifies the minimum spacing in pixels between the top or bottom edge of 
DrawingArea and any child widget. 
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XmNmarginWidth 

Specifies the minimum spacing in pixels between the left or right edge of 
DrawingArea and any child widget. 

XmNresizeCallback 

Specifies the list of callbacks that is called when the DrawingArea is resized. The 
callback reason is XmCRRESIZ 1 ",. 

XmNresizePolicy 

Controls the policy for resizing DrawingArea widgets. Possible values include 
XmRESIZE_NONE (fixed size), XmRESIZE ANY (shrink or grow as needed), and 
XmRESIZEGROW (grow only). 

Inherited Resources 

DrawingArea inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottornShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCaUback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadcwThickness 


XrrCShadoWThickness 


short 


0 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadov/Pixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitivc 


XmCScnsitive 


Boolean 


True 


G 


XroNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XniNbackfroundPixmaD 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


c 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int reason; 
XEvent * event; 

Window window; 
} XmDrawingAreaCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

window Is set to the widget window. 

Behavior 

DrawingArea behavior is summarized below. 

<KeyDown>, <KeyUp>, <BtnDown>, <BtnUp>: 

The callbacks for XmNinputCallback are called when a keyboard key or mouse but- 
ton is pressed or released. 

<Expose>: 

The callbacks for XmNexposeCallback are called when the widget receives an expo- 
sure event. 

< Widget Resize >: 

The callbacks for XmNresizeCallback are called when the widget is resized. 

Default Translations 

The following are DrawingArea's default translations: 

<BtnlDown>: Arm() 
<BtnlUp>: ActivateQ 
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<EnterWindow>: 
<FocusIn>: 



Enter() 
FocusIn() 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 

RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateDrawingArea(3X), and XmManager(3X). 
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NAME 

XmDrawnButton - the DrawnButton widget class. 

SYNOPSIS 

#include <Xm/DrawnB.h> 

DESCRIPTION 

The DrawnButton widget consists of an empty widget window surrounded by a shadow border. It 
provides the application developer with a graphics area that can have PushButton input semantics. 

Callback types are defined for widget exposure and resize to allow the application to redraw or 
reposition its graphics. If the DrawnButton widget has a highlight and shadow thickness, the 
application should not draw in that area. To avoid drawing in the highlight and shadow area, 
create the graphics context with a clipping rectangle for drawing in the widget. The clipping rec- 
tangle will take into account the size of the widget's highlight thickness and shadow. 

Classes 

DrawnButton inherits behavior and resources from Core, XmPrimitive, and XmLabel 
Classes. 

The class pointer is xmDrawnButtonWidgetClass. 
The class name is XmDrawnButton. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmDrawnButton Resource Set 


Name 


Class 


Type 


Default 


Access 

C 


XmNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


XmNarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNdisarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNexposeCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNpushButtonEnabled 


XmCPushButtonEnabled 


Boolean 


False 


CSG 


XmNresizeCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNshadotffype 


XmCShadowType 


unsigned char 


XmSHADOW ETCHED IN 


CSG 



XmNactivateCallbadc 

Specifies the list of callbacks that is called when the widget becomes selected. The 
reason sent by the callback is XmCR_ACTIVATE. 

XmNarmCallback 

Specifies the list of callbacks that is called when the widget becomes armed. The 
reason sent by the callback is XmCR ARM. 

XmNdisarmCallback 

Specifies the list of callbacks that is called when the widget becomes disarmed. The 
reason sent by the callback is XmCR_DISARM. 

XmNexposeCallback 

Specifies the list of callbacks that is called when the widget receives an exposure 
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event. The reason sent by the callback is XmCR EXPOSE. 

XmNpushButtonEnabled 

Enables or disables the three-dimensional shadow drawing as in PushButton. 

XmNresizeCallback 

Specifies the list of callbacks that is called when the widget receives a resize event. 
The reason sent by the callback is XmCR_RESIZE. The event returned for this 
callback is NULL. 

XmNshadowType 

Describes the drawing style for the DrawnButton. This resource can have the fol- 
lowing values: 

• XmSHADOW_IN - draws the DrawnButton such that the shadow appears 
inset. This means that the bottom shadow visuals and top shadow visuals are 
reversed. 

• XmSHADOW_OUT - draws the DrawnButton such that the shadow appears 
outset. 

• XmSHADOW ETCHED IN - draws the DrawnButton using a double line. 
This gives the effect of a line etched into the window. The thickness of the dou- 
ble line is equal to the value of XmNshadowThickness. 

• XmSHADOWETCHEDOUT - draws the DrawnButton using a double line. 
This gives the~effect of a line coming out of the window. The thickness of the 
double line is equal to the value of XmNshadowThickness. 



Inherited Resources 

DrawnButton inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmLabel Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerator 


XmCAccelerator 


String 


NULL 


CSG 


XmNacceleratoiText 


XmCAcceleratoiText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


'\0' 


CSG 


XmNlabelType 


XmCLabenype 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


0 


CSG 


XmNmarginHeight 


XmCMarginHeight 


short 


dynamic 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


0 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


0 


CSG 


XmNmarginTop 


XmCMarginTop 


short 


0 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


dynamic 


CSG 


XmNmnemonic 


XmCMnemonic 


char 


•\0' 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 
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Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowCblor 


XmCForegiound 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNfoieground 


Xmufroreground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 




XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XniNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThidcness 


XmCHighlightThidcness 


short 


0 


CSG 


XmNshadcwThickness 


XmCShadowThickness 


short 


2 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 




Core Resource Set 


Name 


Class 




Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallbadt 


XtCallbackList 


NULL 


C 


XmNheighl 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWnenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 
{ 

int reason; 
XEvent * event; 

Window window; 
} XmDrawnButtonCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. NULL is returned by the 

event for XmNresizeCallback. This event will be NULL for the XmNac- 
tivateCallback if the callback was triggered when Primitive's resource 
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XmNtraversalOn was True or if the callback was accessed through the 
ArmAndActivate action routine. 

window Is set to the window ID in which the event occurred. 

Behavior 

<BtnlDown>: 

A selection on the DrawnButton causes its shadow to be drawn in the selected state 
if the XmNpushButtonEnabled flag is set to True. The callbacks for XmNarmCall- 
back are also called. 

<BtnlUp>: 

If <BtnlUp> occurs when the pointer is within the DrawnButton, the shadows are 
redrawn in the unselected state if the XmNpushButtonEnabled flag is set to True. 
The callbacks for XmNactivateCallback are called, followed by callbacks for 
XmdisarmCallback. 

If <BtnlUp> occurs when the pointer is outside the DrawnButton, the callbacks for 
XmNdisarmCallback are called. 

< Leave Window > : 

If the mouse button is pressed and the cursor leaves the DrawnButtons window, the 
shadow is redrawn to its unselected state if the XmNpushButtonEnabled flag is set 
to True. 

< Enter Window >: 

If the mouse button is pressed and the cursor reenters the DrawnButton window, 
the shadow is drawn in the same manner as when the button was first selected. 

Default Translations 

<BtnlDown>: 
<BtnlUp>: 

< Key > Return: 

< Key > space: 
<EnterWindow>: 

< LeaveWindow > : 

Keyboard Traversal 

For information on keyboard traversal, see the man page for XmPrimitive(3X) and its sec- 
tions on behavior and default translations. 

RELATED INFORMATION 

Core(3X), XmCreateDrawnButton, XmLabeI(3X), XmPrimitive(3X), XmPushButton, and 
XmSeparator(3X). 



Arm() 

Activate() 

Disarm() 

ArmAndActivateO 
ArmAndActivateO 
Enter() 
LeaveQ 
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NAME 

XmFileSelectionBox - the FileSelectionBox widget class. 

SYNOPSIS 

#include <Xm/FileSB.h> 

DESCRIPTION 

FileSelectionBox traverses through directories, views the files in them, and then selects a file. 
A FileSelectionBox has four main areas: 

• A directory mask that includes a filter label and a directory mask input field used to specify the 
directory that is to be examined. 

• A scrollable list of file names. 

• A text input field for directly typing in a file name. 

• A group of PushButtons, labeled OK, Filter, Cancel, and Help. 

One additional WorkArea child maybe added to the FileSelectionBox after creation. 

The user can select a file by scrolling through the list of file names and selecting the desired file 
or by entering the file name directly into the text edit area. Selecting a file from the list will cause 
that file name to appear in the file selection text edit area. 

The user may select a new file as many times as desired. The application is not notified until the 
user selects the OK PushButton or presses the return key while the selection text edit area has the 
keyboard focus. 

FileSelectionBox initiates a file search when any of the following occurs: 

• The function XtSetValues is used to change the directory mask. 

• The user activates the Filter PushButton. 

• The application calls XmFileSelectionDoSearch. 

• The user presses the return key while the directory mask input field has the keyboard focus. 

This may be useful when an application creates a new file and wants to incorporate it into the file 
list. 

Classes 

FileSelectionBox inherits behavior and resources from Core, Composite, Constraint, 
XmManager, XmBulletinBoard, and XmSelectionBox. 

The class pointer is xmFileSelectionBoxWidgetClass. 

The class name is XmFileSelectionBox. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGet Values (G), or is not applicable (N/A). 
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XmFikSekctionBox Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdirMask 


XmCDirMask 


XmString 




CSG 


XmNdirSpec 


XmCDirSpec 


XmString 


NULL 


CSG 


XmNfileSearchProc 


XmCFileScarchProc 


XtProc 


sec below 


CSG 


XmNfilterLabelString 


XmCFilterLabelString 


XmString 


"File Filter" 


CSG 


XmNlistUpdated 


XmCListUpdated 


Boolean 


True 


CSG 



XmNdirMask 

Specifies the directory mask used in determining the files to be displayed in the list 
box. 

XmNdirSpec 

Specifies the full file specification. This resource overrides the XmN text St ring 
resource in SelectionBox. 

XmNfileSearchProc 

Specifies a directory search procedure to replace the default file selection search 
procedure. FileSelectionBox's default file search procedure fulfills the needs of 
most applications. Because it is impossible to cover the requirements of all applica- 
tions, you can replace the default search procedure. 

The file search procedure is called with two arguments: the FileSelectionBox 
widget and the XmFileSelectionCallbackStruct structure. The callback structure 
contains all required information to conduct a directory search, including the 
current file search mask. Once called, it is up to the search routine to generate a 
new list of files and update the file selection widget by using XtSet Values. 

The following attributes must be set: XmNitems, XmNitemsCount, XmNlistUp- 
dated, and XmNdirSpec. Set XmNitems to the new list of files. If there are no files, 
set this attribute to NULL. This sets the XmNitems attribute associated with Selec- 
tionBox. 

If there are no files, set XmNitemsCount to zero. This sets the XmNitemsCount 
associated with SelectionBox. Always set XmNlistUpdated to True when updating 
the file list using a search procedure, even if there are no files. Setting XmNdirSpec 
is optional, but recommended. Set this attribute to the full file specification of the 
directory searched. The directory specification is displayed above the list box. 

XmNfilterLabelString 

Specifies the string value for the label located above the DIR_MASK text entry 
field. 

XmNlistUpdated 

Specifies an attribute that is set only by the file search procedure. Set to True, if the 
file list has been updated. 

Inherited Resources 

FileSelectionBox inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 
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XmSelectionBox Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNapplyCallback 


XmCCallback 


XtCallbackList 


NULL 


c 


XmNapplyLabclStrifjg 


XmCApptyLabelString 


XmString 


"Filter" 


CSG 


XmNcancelCallback 


XmCCallback 


XtCallbackList 


NULL 




XmNcancelLabclString 


XmCXmString 


XmString 


"Cancel* 


CSG 


XmNdialogType 


XmCDialogType 


unsigned cbar 


XmOIALOG FILE SELECTION 


CG 


XmNhelpLabclString 


XmCXmString 


XmString 


"Help" 


CSG 


XmNlistltemCount 


XmCItemCount 


int 


0 


CSG 


XmNlistltems 


XmCItems 


XmStringList 


NULL 


CSG 


XmNlistLabelString 


XmCXmString 


XmString 


"Files" 


CSG 


XmNlistVisibleltemCount 


XmCVisibleltemCount 


int 


8 


CSG 


XmNminimizeButtoos 


XmCMinimizeButtons 


Boolean 


False 


CSG 


XmNmustMatch 


XmCMustMatch 


Boolean 


0 


CSG 


XmNnoMatchCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNokCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNokLabelString 


XmCXmString 


XmString 


"OK" 


CSG 


XmNselectionLabelString 


XmCXmString 


XmString 


"Selection" 


CSG 


XmNtextAccelerators 


XmCTextAccelerators 


XtTranslations 


see description 


C 


XmNtextColumns 


XrnCText Columns 


int 


31 


CSG 


XmNtext String 


XmCTextString 


XmString 


NULL 


CSG 



XmBulktinBoard Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowOverlap 


XmCAllowOverlap 


Boolean 


True 


CSG 


XmNautoUnmanage 


XmCAutoUnmanage 


Boolean 


False 


CSG 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


CSG 


XmNcancelButton 


XmCWidget 


Widget 


Cancel button 


SG 


XmNdefaultButton 


XmCWidget 


Widget 


OK button 


SG 


XmNdefaultPosition 


XmCDefaultPosition 


Boolean 


True 


CSG 


XmNdialogStyle 


XmCDialogStyle 


unsigned char 


dynamic 


CSG 


XmNdialogTitle 


XmCXmString 


XmString 


NULL 


CSG 


XmNfocusCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNlabelFontList 


XmCLabelFontList 


XmFontList 


NULL 


CSG 


XmNmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


10 


CSG 


XmNnoResize 


XmCNoResize 


Boolean 


False 


CSG 


XmNresizePolicy 


XmCResizePolicy 


unsigned cbar 


XmRESIZEANY 


CSG 


XmNshadov/iype 


XmCShadoWiype 


unsigned char 


XmSHADOWOUT 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRINGDIRECTIONLTOR 


CSG 


XmNtextFontList 


XmCTextFontList 


XmFontList 


NULL 


CSG 


XmNtextTranslations 


XmCTranslations 


XtTranslations 


NULL 


C 


XmNunmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 
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XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNboCtomShadowPixmap 


XroCBottomShadtarPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadcwThidtness 


XmCShadoWThickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBadkground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIEDPEXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPoeition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixtnap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PDCMAP 


CSG 


XmNborderWIdth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmN screen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 



typedef struct 

{ 

int 

XEvent 

XmString 

int 

XmString 
int 



reason; 
* event; 
value; 
length; 
mask; 
mask length; 



} XmFileSelectionBoxCallbackStruct; 
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reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

value Specifies the value of the current XmNdirSpec. 

length Specifies the number of bytes of the structure pointed to by value. 

mask Specifies the current value of XmNdirMask. 

maskjength Specifies the number of bytes of the structure pointed to by mask. 



Behavior 

FileSelectionBox inherits behavior from SelectionBox and BulletinBoard; below is an addi- 
tion to that behavior. 



< Apply Button Activated > : 

A new file search begins when the apply button is activated. 



Default Translations 

FileSelectionBox inherits SelectionBox's default translations. See the man page for 
XmSelectionBox(3X). 



Default Accelerators 

The following are the default accelerator translations added to descendants of a Bulletin- 
Board if the parent of the BulletinBoard is a DialogShell: 



#override 

<Key>Fl: Help() 

< Key > Return: Return() 

<Key>KP_Enten ReturnQ 



Default Text Accelerators 

The following are the default text accelerators inherited from SelectionBox: 



#override 
<Key>Up: 

< Key > Down: 
<Key>Fl: 

< Key > Return: 
<Key>KP_Enten 



UpOrDown(O) 

UpOrDown(l) 

Help() 

Return() 

ReturnQ 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmBulIetinBoard(3X), 
XmCreateFUeSelectionBox(3X),XmCreateFileSelectionDialog(3X), 
XmFileSelectionBoxGetChild(3X), XmFileSelectionDoSearch(3X), XmManager(3X), and 
XmSelectionBox(3X), 



HISTORY/DIRECTION 

HP-UX Programs using FileSelectionBox must be linked with /lib/libPW.a. 
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NAME 

XmFUeSelectioiiBoxGetChild - a FileSelectionBox function that is used to access a component. 

SYNOPSIS 

#include <Xm/FileSB.h> 

Widget XmFileSelectionBoxGetChild (widget, child) 
Widget widget; 
unsigned char child; 

DESCRIPTION 

XmFileSelectionBoxGetChild is used to access a component within a FileSelectionBox. The 
parameters given to the function are the FileSelectionBox widget and a value indicating which 
child to access. 

widget Specifies the FileSelectionBox widget ID. 

child Specifies a component within the FileSelectionBox. The following are legal values 

for this parameter 

• XmDIALOGAPPLYBUTTON. 

• XmDIALOG CANCEL BUTTON. 

• XmDIALOGDEFAULTBUTTON. 

• XmDIALOGFILTERIABEL. 

• XmDIAIXXi FILTER TEXT. 

• XmDIALOGHELPBUTTON. 

• XmDIALOGLIST. 

• XmDIALOGLISTLABEL. 

• XmDIALOGOKBUTTON. 

• XmDIALOGSELECTIONLABEL. 

• XmDIALOG TEXT. 

For a complete definition of FileSelectionBox and its associated resources, see 
XmFileSeIectionBox(3X). 

RETURN VALUE 

Returns the widget ID of the specified FileSelectionBox child. 

RELATED INFORMATION 

XmFileSelectionBox(3X). 
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NAME 

FileSelectionDoSearch - a FileSelectionBox function that initiates a directory search. 

SYNOPSIS 

#include <Xm/FiIeSB.h> 

void XmFileSelectionDoSearch (widget, damask) 
Widget widget; 
XmString dirmask; 

DESCRIPTION 

XmFileSelectionDoSearch initiates a directory search. If the dirmask parameter is not NULL, the 
directory mask is updated before the search is initiated. 

widget Specifies the FileSelectionBox widget ID. 

dirmask Specifies the directory mask used in determining the files displayed in the 

FileSelectionBox list This sets the XmNdirMask attribute associated with 
XmCreateFileSelectionBox. This is an optional attribute. If you do not specify a 
directory mask, the current directory mask is used. 

For a complete definition of FileSelectionBox and its associated resources, see 
XmFileSelectionBox(3X). 



RELATED INFORMATION 

XmFileSelectionBox(3X). 
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NAME 

XmFontListAdd - a compound string function that creates a new font list. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmFontList XmFontListAdd {oldlist, font, charset) 
XmFontList oldlisf, 
XFontStruct * font, 

XmStringCharSet charset; 



DESCRIPTION 

XmFontListAdd creates a new font list consisting of the contents of the oldlist and the new font list 
element being added. This function deallocates the oldlist after extracting the required informa- 
tion; therefore, do not reference oldlist thereafter. 

oldlist Specifies a pointer to the font list to which an entry will be added. 

font Specifies a pointer to a font structure for which the new font list is generated. 

This is the structure returned by the XLib XLoadQueryFont function. 

charset Specifies the character set identifier for the font. This can be 

XmSTRINGDEFAULTCHARSET. 

RETURN VALUE 

Returns a new font list. 



RELATED INFORMATION 

XmFontListCreate(3X). 
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NAME 

XmFontListCreate - a compound string function that creates a font list. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmFontList XmFontListCreate (font, charset) 
XFontStruct * fonts, 

XmStringCharSet charset, 

DESCRIPTION 

XmFontListCreate creates a new font list with a single element specified by the provided font and 
character set. At also allocates the space for the font list 

font Specifies a pointer to a font structure for which the new font list is generated, this 

is the structure returned by the XLib XLoadQueryFont function. 

charset Specifies the character set identifier for the font. This can be 

XmSTRINGDEFAULTCHARSET. 

RETURN VALUE 

Returns a new font list. 

RELATED INFORMATION 

XmFontLis(Add(3X), XmFontListFree(3X), XmStringBaseline(3X), XmStringByteCompare(3X), 
XmStringCompare(3X), XmStringConcat(3X), XmStringCopy(3X), XmStringCreate(3X), 
XmStringCreateLtoR(3X), XmStringDirectionCreate(3X), XmStringDraw(3X), 
XmStringDrawImage(3X), XmStringDrawUnderline(3X), XmStringEmpty(3X), 
XmStringExtent(3X), XmStringFree(3X), XmStringFreeContext(3X), XmStringGetLtoR(3X), 
XmStringGetNextComponent(3X), XmStringGetNextSegment(3X), XmStringHeight(3X), 
XmStringInitContext(3X), XmStringLength(3X), XmStringLineCount(3X), 
XmStringNConcat(3X), XmStringNCopy(3X), XmStringPeekNextComponent(3X), 
XmStringSegmentCreate(3X), XmStringSeparatorCreate(3X), and XmStringWidth(3X). 
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NAME 

XmFontListFree - a compound string function that recovers memory used by a font list. 

SYNOPSIS 

#include <Xm/XmJi> 

void XmFontListFree (list) 

XmFontList list, 

DESCRIPTION 

XmFontListFree recovers memory used by a font list. 

list Specifies the font list to be freed. 

RELATED INFORMATION 

XmFontListCreate(3X). 
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NAME 

XmForm - the Form widget class. 

SYNOPSIS 

#include <Xm/Form.h> 

DESCRIPTION 

Form is a container widget with no input semantics of its own. Constraints are placed on children 
of the Form to define attachments for each of the child's four sides. These attachments can be to 
the Form, to another child widget or gadget, to a relative position within the Form, or to the initial 
position of the child. The attachments determine the layout behavior of the Form when resizing 
occurs. 

Classes 

Form inherits behavior and resources from Core, Composite, Constraint, XmManager, and 
XmBuIletinBoard classes. 

The class pointer is xmFormWidgetClass. 

The class name is XmForm. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmForm Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNfractionBase 


XmCMaxValue 


int 


100 


CSG 


XmNhorizontalSpacing 


XmCSpacing 


int 


0 


CSG 


XmNrubberPositioning 


XmCRubberPositioning 


Boolean 


False 


CSG 


XmNverticalSpacing 


XmCSpacing 


int 


0 


CSG 



XmNfractionBase 

Specifies the denominator used in calculating the relative position of a child widget 
using XniATTACH_POSITION constraints. 

XmNhorizontalSpacing 

Specifies the offset for right and left attachments. 

XmNrubberPositioning 

Indicates the default attachment for a child of the Form. If this Boolean resource is 
set to False, then the left and top of the child defaults to being attached to the left 
and top side of the Form. If this resource is set to True, then the child defaults to 
being attached to its initial position in the Form. 

XmNverticalSpacing 

Specifies the offset for top and bottom attachments. 
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XmForm Constraint Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomAttachment 


XmCAttachment 


unsigned char 


XmATTACH NONE 


CSG 


XmNbottomOftset 


XmCOffcet 


int 


0 


CSG 


XmNbottomPosition 


XmCAttachment 


int 


0 


CSG 


XmNbottomWidget 


XmCWidget 


Widget 


NULL 


CSG 


XmNleftAttachment 


XmCAttachment 


unsigned char 


XmATTACH NONE 


CSG 


XmNleftOf&et 


XmCOffcet 


int 


0 


CSG 


XmNleftPosition 


XmCAttachment 


int 


0 


CSG 


XmNleftWidget 


XmCWidget 


Widget 


NULL 


CSG 


XmNresizable 


XmCBoolean 


Boolean 


True 


CSG 


XmNrightAttachment 


XmCAttachment 


unsigned char 


XmATTACH NONE 


CSG 


XmNrightOffcet 


XmCOffcet 


int 


0 


CSG 


XmNrightPosition 


XmCAttachment 


int 


0 


CSG 


XmNrightWidget 


XmCWidget 


Widget 


NULL 


CSG 


XmNtopAttachment 


XmCAttachment 


unsigned char 


XmATTACH NONE 


CSG 


XmNtopOffcet 


XmCOffcet 


int 


0 


CSG 


XmNtopPosition 


XmCAttachment 


int 


0 


CSG 


XmNtopWidget 


XmCWidget 


Widget 


NULL 


CSG 



XmNbottomAttachment 

Specifies attachment of the bottom side of the child. It can have the following data 
values: 

• XniATTACHNONE - do not attach this side. 

• XmATTACHFORM - attach the bottom side of the child to the bottom side of 
the Form. 

• XmATTACH OPPOSITE FORM - attach the bottom side of the child to the 
top side of the Form. 

• XmATTACH_WIDGET - attach the bottom side of the child to the top side of 
the widget or gadget specified in the XmNbottomWidget resource. 

• XmATI ACH OPPOSITE WIDGET - attach the bottom side of the child to the 
bottom side of the widget or gadget specified in the XmNbottomWidget 
resource. 

• XmATTACH_POSrnON - attach the bottom side of the child to a relative 
position in the Form. This position is specified by the XmNbottomPosition 
resource. 

• XmATTACH_SELF - attach the bottom of the child to its initial position in the 
Form. 

XmNbottomOffset 

Specifies the constant offset between the bottom side of the child and the object to 
which it is attached. This resource is ignored if XmNbottomAttachment is set to 
XmATTACH_POSinON. The relationship established remains, regardless of any 
resizing operations that occur. 

XmNbottomPosition 

Determines the relative position of the bottom side of the child. The relative posi- 
tion is a fractional value of the height of the Form. The fractional value is equal to 
the value of this resource divided by the value of XmNfractionBase. This resource 
is only used if XmNbottomAttachment is set to XmATTACH POSiTION. 

XmNbottomWidget 

Specifies the widget or gadget to which the bottom side of the child is attached. 
This resource is used if XmNbottomAttachment is set to either 
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XmATTACH WIDGET or XmATTACH OPPOSITE WIDGET. 
XmNleftAttachment 

Specifies attachment of the left side of the child. It can have the following data 
values: 

• XmATTACH_NONE - do not attach this side. 

• XmATTACHPORM - attach the left side of the child to the left side of the 
Form. 

• XmATTACH OPPOSITE FORM - attach the left side of the child to the right 
side of the Form. 

• XmATTACH WIDGET - attach the left side of the child to the right side of the 
widget or gadget specified in the XmNleftWidget resource. 

• XmATTACHOPPOSITEWIDGET - attach the left side of the child to the left 
side of the widget or gadget specified in the XmNleftWidget resource. 

• XmATTACH_POSITION - attach the left side of the child to a relative position 
in the Form. This position is specified by the XmNleftPosition resource. 

• XmATTACH_SELF - attach the left side of the child to its initial position in the 
Form. 

XmNleftOfiset 

Specifies the constant offset between the left side of the child and the object to 
which it is attached. This resource is ignored if XmNleftAttachment is set to 
XmATTACH_POSinON. The relationship established remains, regardless of any 
resizing operations that occur. 

XmNleftPosition 

Determines the relative position of the left side of the child. The relative position is 
a fractional value of the width of the Form. The fractional value is equal to the 
value of this resource divided by the value of XmNfractionBase. This resource is 
only used if XmNleftAttachment is set to XmATTACH POSITION. 

XmNleftWidget 

Specifies the widget or gadget to which the left side of the child is attached. This 
resource is used if XmNleftAttachment is set to either XmATTACH WIDGET or 
XmATTACH OPPOSITE WIDGET. 

XmNresizable 

Specifies whether a child widget can be resized by the Form. The default value is 
True. 

XmNrightAttachment 

Specifies attachment of the right side of the child. It can have the following data 
values: 

• XmATTACH NONE - do not attach this side. 

• XmATTACH_FORM - attach the right side of the child to the right side of the 
Form. 

• XmATTACH_OPPOSITE_FORM - attach the right side of the child to the left 
side of the Form. ~ 

• XmATTACH_WIDGET - attach the right side of the child to the left side of the 
widget or gadget specified in the XmNrightWidget resource. 

• XmATTACH OPPOSITE WIDGET - attach the right side of the child to the 
right side of the widget or gadget specified in the XmNrightWidget resource. 

• XmATTACH_POSmON - attach the right side of the child to a relative posi- 
tion in the Form. This position is specified by the XmNrightPosition resource. 

• XmATTACH_SELF - attach the right side of the child to its initial position in 
the Form. 
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XmNrightOffset 

Specifies the constant offset between the right side of the child and the object to 
which it is attached. This resource is ignored if XmNrightAttachment is set to 
XmATTACHPOSITION. The relationship established remains, regardless of any 
resizing operations that occur. 

XmNrightPosition 

Determines the relative position of the right side of the child. The relative position 
is a fractional value of the width of the Form. The fractional value is equal to the 
value of this resource divided by the value of XmNfractionBase. This resource is 
only used if XmNrightAttachment is set to XmATTACHPOSITION. 

XmNrightWidget 

Specifies the widget or gadget to which the right side of the child is attached. This 
resource is used if XmNrightAttachment is set to either XmATTACH_ WIDGET or 
X111ATTACH OPPOSITE WIDGET. 

XmNtopAttachment 

Specifies attachment of the top side of the child. It can have the following data 
values: 

• XmATTACHNONE - do not attach this side. 

• XmATTACH_FORM - attach the top side of the child to the top side of the 
Form. 

• XmATXACH_OPPOSITE_FORM - attach the top side of the child to the bot- 
tom side of the Form. 

• XmATTACH_WIDGET - attach the top side of the child to the bottom side of 
the widget orgadget specified in the XmNtopWidget resource. 

• XmATTACH OPPOSITE WIDGET - attach the top side of the child to the top 
side of the widget or gadget specified in the XmNtopWidget resource. 

• XmATEACH_POSrnON - attach the top side of the child to a relative position 
in the Form. This position is specified by the XmNtopPosition resource. 

• XmATTACH_SELF - attach the top side of the child to its initial position in the 
Form. 

XmNtopOffset 

Specifies the constant offset between the top side of the child and the object to 
which it is attached. This resource is ignored if XmNtopAttachment is set to 
XmATTACH_POSrnON. The relationship established remains, regardless of any 
resizing operations that occur. 

XmNtopPosition 

Determines the relative position of the top side of the child. The relative position is 
a fractional value of the height of the Form. The fractional value is equal to the 
value of this resource divided by the value of XmNfractionBase. This resource is 
only used if XmNtopAttachment is set to XmATTACH POSITION. 

XmNtopWidget 

Specifies the widget or gadget to which the top side of the child is attached. This 
resource is used if XmNtopAttachment is set to either XmATTACH WIDGET or 
XmATTACH OPPOSITE WIDGET. 

Inherited Resources 

Form inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 
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XmBulktin Board Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowOverlap 


XmCAllowOverlap 


Boolean 


True 


N/A 


XmNautoUnmanage 


XmCAutoUnmanage 


Boolean 


True 


N/A 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


N/A 


XmNcancelButton 


XmCWidget 


Widget 


NULL 


N/A 


XmNdefaultButton 


XmCWidget 


Widget 


NULL 


N/A 


XmNdefaultPosition 


XmCDefaultPosition 


Boolean 


True 


N/A 


XmNdialogStyle 


XmCDialogStyle 


unsigned char 


dynamic 


N/A 


XmNdialogTitle 


XmCXmString 


XmString 


NULL 


N/A 


XmNfocusCallbadc 


XmCCallback. 


XtCallbadcList 


NULL 


C 


XmNlabelFontList 


XmCLabelFontList 


XmFontList 


NULL 


N/A 


XmNmapCallback. 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


N/A 


XmNmargjnWidth 


XmCMarginWidth 


short 


10 


N/A 


XmNnoResize 


XmCNoResize 


Boolean 


False 


N/A 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZEANY 


CSG 


XmNshadoWType 


XmCShadoWIype 


unsigned char 


XmSHADOWOUT 


N/A 


XroNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


N/A 


XmNtextFontList 


XmCTextFontList 


XmFontList 


NULL 


N/A 


XmNtextTranslations 


XmCTranslations 


XtTra relations 


NULL 


N/A 


XmNunmapCallbadc 


XmCCallback 


XtCallbadcList 


NULL 


C 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallbadc 


XtCallbadcList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNbighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadoWrhickness 


XmCShadoWThidtness 


short 


0 


N/A 


XmNtopShadowColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPDCELS 


CSG 


XmNuserData 


XmCUserData 


caddr_t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNacccleratois 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNanoestoiScnsitive 


XmCSensitivc 


Boolean 


True 


G 


XmNback^round 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixniap 


XmCPixroap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmGDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadc. 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

Form inherits BulletinBoard's behavior. 

Default Translations 

Form inherits BulletinBoard's default translations. 

Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateForm, 
XmCreateFormDialog(3X), and XmManager(3X). 
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NAME 

XmFrame - the Frame widget class. 

SYNOPSIS 

#include <Xm/Frame.h> 

DESCRIPTION 

Frame is a very simple manager used to enclose a single child in a border drawn by Frame. It uses 
the Manager class resources for border drawing and performs geometry management such that its 
size will always match its child's size plus the margins defined for it 

Frame is most often used to enclose other managers when the application developer desires the 
manager to have the same border appearance as the primitive widgets. Frame can also be used to 
enclose primitive widgets that do not support the same type of border drawing. This will give 
visual consistency when developing applications using diverse widget sets. 

If the Frame's parent is a Shell widget, then XmNshadowType is set to XmSHADOWOUT and 
Manager's resource XmNshadowThickness is set to one by default 

Classes 

Frame inherits behavior and resources from the Core, Composite, Constraint, and 
XmManager classes. 

The class pointer is xmFrameWidgetClass. 
The class name is XmFrame. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetVahies (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmFrame Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNmarginWidth 


XmCMarginWidth 


short 


0 


CSG 


XmNmarginHeight 


XmCMargiriHeight 


short 


0 


CSG 


XmNshadcwType 


XmCShadcwType 


unsigned char 


XmSHADOW ETCHED IN 


CSG 



XmNmarginWidth 

Specifies the padding space on the left and right sides between the child of Frame 
and Frame's shadow drawing. 

XmNmarginHeight 

Specifies the padding space on the top and bottom sides between the child of Frame 
and Frame's shadow drawing. 

XmNshadowType 

Describes the drawing style for Frame. This resource can have the following values: 

• XmSHADOW IN - draws Frame such that it appears inset. This means that the 
bottom shadow visuals and top shadow visuals are reversed. 

• XmSHADOW OUT - draws Frame such that it appears outset. 
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• XmSHADOW ETCHED IN - draws Frame using a double line giving the 
effect of a line etched into the window. The thickness of the double line is equal 
to the value of XmNshadowThickness. This is the default if Frame's parent is a 
Shell widget. 

• XmSHADOW ETCHED OUT - draws Frame using a double line giving the 
effect of a line coming out of the window. The thickness of the double line is 
equal to the value of XmNshadowThickness. This is the default except when 
Frame's parent is a Shell widget. 

Inherited Resources 

Frame inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForegrouod 


Pixel 


dynamic 


CSG 


XrnNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForegrouod 


Pixel 


dynamic 


CSG 


XmNbelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN highlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadoaThickness 


XmCShadoaThickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInseitPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNoorderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Hewlett-Packard Company 



-2- 



Jul 27, 1989 



XmFrame(3X) 



XmFrame(3X) 



Default Translations 

<EnterWindow>: Enter() 

<FocusIn>: FocusIn() 

<BtnlDown>: Arm() 

<BtnlUp>: Activate() 

RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateFrame(3X), and XmManager(3X). 



Hewlett-Packard Company 



-3- 



Jul 27, 1989 



XmGadget (3X) 



XmGadget (3X) 



NAME 

XmGadget - the Gadget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Gadget is a widget class used as a supporting superclass for other gadget classes. It handles sha- 
dow border drawing and highlighting, traversal activation and deactivation, and various callback 
lists needed by gadgets. 

The color and pixmap resources defined by XmManager are directly used by gadgets. If XtSet- 
Values is used to change one of the resources for a manager widget, then all of the gadget children 
within the manager also change. 

Classes 

Gadget inherits behavior and resources from Object and RectObj classes. 
The class pointer is xmGadgetClass. 
The class name is XmGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGet Values (G), or is not applicable (N/A). 



XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhelpCallback 


XmCCallback. 


XtCallbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNMghkghtThickness 


XmCHighlightThidcness 


short 


0 


CSG 


XmNshadcwThickness 


XmCSbadonThickness 


short 


2 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitffype 


XmCUniffype 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



XmNhelpCallback 

Specifies the list of callbacks that is called when the help key sequence is pressed. 
The reason sent by the callback is XmCR HELP. 

XmNhighlightOnEnter 

Specifies whether or not to draw border highlighting. This resource is ignored if 
XmNtraversalOn is True. 

XmNhighlightThickness 

Specifies the thickness of the highlighting rectangle. 

XmNshadowThickness 

Specifies the size of the drawn border shadow. 

XmNtraversalOn 

Specifies traversal activation for this gadget. 
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XmNunitType 

Provides the basic support for resolution independence. It defines the type of units 
a widget will use with sizing and positioning resources. Unless the XmNunitType 
resource is explicitly set, it will default to the unit type of the parent widget. If the 
parent has a unit type of Xml00TH_POINTS, then any of its children whose 
XmNunitType resource is not set will also have a unit type of XmlOOTHPOINTS. 
This feature applies only to widgets whose parents are a subclass of XmManager. 
Widgets whose parents are not subclasses of XmManager will have a unit type of 
XmPIXELS. 

XmNunitType can have the following values: 

• XmPIXELS - all values provided to the widget are treated as normal pixel 
values. This is the default for the resource. 

• XmlOOTH MILLIMETERS - all values provided to the widget are treated as 
1/100 millimeter. 

• XmlOOOTH INCHES - all values provided to the widget are treated as 1/1000 
inch. 

• XmlOOTH POINTS - all values provided to the widget are treated as 1/100 
point. A point is a unit typically used in text processing applications and is 
defined as 1/72 inch. 

• XmlOOTHFONTUNITS - all values provided to the widget are treated as 
1/100-font unit. The value to be used for the font unit is determined in one of 
two ways. The resource XmNfont can be used in a defaults file or on the com- 
mand line. The standard command line options of -fn and -font can also be 
used. The font unit value is taken as the QUAD_WIDTH property of the font. 
The function XmSetFontUnits allows applications to specify the font unit values. 

XmNuserData 

Allows the application to attach any necessary specific data to the gadget. An inter- 
nally unused resource. 

Inherited Resources 

Gadget inherits the following resources from the named superclass. For a complete descrip- 
tion of these resources, refer to the man page for that superclass. 



RectObj Resource Set 


Name 


Class 


T>pe 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 



Behavior 

Gadgets cannot have translations associated with them. Because of this, a Gadget's behavior 
is determined by the Manager widget into which the Gadget is placed. The following are 
types of events which are caught by a Manager widget and forwarded to a Gadget: 
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• ButtonPress 

• ButtonRelease 

• EnterNotify 

• LeaveNotify 

• Focusln 

• FocusOut 

• MotionNotify 

Refer to XmManager(3X) for a discussion of the translations supported by all Manager 
widgets. 

RELATED INFORMATION 

Object (3X), RectObj(3X), and Xm Manager (3X). 
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NAME 

XmGetAtomName - a function that returns the string representation for an atom. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/AtomMgr.h> 

String XmGetAtomName (display, atom) 
Display * display; 

Atom * atom; 

DESCRIPTION 

XmGetAtomName returns the string representation for an atom. It mirrors the Xlib interfaces for 
atom management, but provides client side caching. When and where caching is provided in Xlib, 
the routines will become pseudonyms for the Xlib routines. 

display Specifies the connection to the X server. 

atom Specifies the atom for the property name you want returned. 

RETURN VALUE 

Returns a string. 
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NAME 

XmGetMenuCursor - a RowColumn function that returns the cursor ID for the current menu 
cursor. 

SYNOPSIS 

Cursor XmGetMenuCursor (display) 

Display * display; 

DESCRIPTION 

XmGetMenuCursor queries the menu cursor currently being used by this client on the specified 
display and returns the cursor ID. 

display Specifies the display whose menu cursor is to be queried. 

For a complete definition of the menu cursor resource, see XmRowColumn(3X). 
RETURN VALUE 

Returns the cursor ID for the current menu cursor or the value none if a cursor is not yet defined. 
A cursor will not be defined if the application makes this call before the client has created any 
menus on the specified display. 

RELATED INFORMATION 

XmRowColumn(3X). 
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NAME 

XmGetPixmap - a pixmap caching function that generates a pixmap, stores it in a pixmap cache, 
and returns the pixmap. 



SYNOPSIS 

#include <Xm/Xm.h> 

Pixmap XmGetPixmap {screen, image juune, foreground, background) 

Screen * screen; 

char * image name; 

Pixel foreground; 

Pixel background; 



DESCRIPTION 

XmGetPixmap uses the parameter data to perform a lookup in the pixmap cache to see if a pix- 
map has already been generated which matches the data. If one is found, a reference count is 
incremented and the pixmap is returned. Applications should use XmDestroyPixmap when the 
pixmap is no longer needed. 

If a pixmap is not found, image juane is used to perform a lookup in the image cache. If an image 
is found, it is used to generate the pixmap, which is then cached and returned. 

If an image is not found, the imagejtame is used as a file name, and a search is made for an X10 
or Xll bitmap file. If it is found, the file is read, converted into an image, and cached in the 
image cache. The image is then used to generate a pixmap, which is cached and returned. 

Several paths are searched to find the file. The user can specify an environment variable 
XBMLANGPATH, which is used to generate one set of paths. See XtInitialize(3X) for an expla- 
nation of using this environment variable. If XBMLANGPATH is not set, the following path 
names are searched: 



/usr/lib/Xll/%L/bitmaps/%N/%B 
/usr/lib/Xll/%L/bitmaps/%B 
/usr/lib/Xll/bitmaps/%B 
/usr/include/Xll/bitmaps/%B 



Parameter descriptions are listed below. 



screen Specifies the display screen on which the pixmap is to be drawn and is used 

to ensure that the pixmap matches the visual required for the screen. 

imagejtame Specifies the name of the image to be used to generate the pixmap. 

foreground Combines the image with the foreground color to create the pixmap if the 

image referenced is a bit-per-pixel image. 

background Combines the image with the background color to create the pixmap if the 

image referenced is a bit-per-pixel image. 



RETURN VALUE 

Returns a pixmap when successful; returns XmUNSPECIFIED PIXMAP if the image correspond- 
ing to the imagejtame cannot be found. 



RELATED INFORMATION 

XmDestroyPixmap(3X), XmInstalIImage(3X), and XmUninstallImage(3X). 
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NAME 

Xmlnstalllmage - a pixmap caching function that adds an image to the pixmap cache. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean Xmlnstalllmage (image, imagejiame) 
Xlmage * image; 

char * image jtame\ 

DESCRIPTION 

Xmlnstalllmage stores an image in an image cache that can later be used to generate a pixmap. 
Part of the installation process is to extend the resource converter used to reference these images. 
The resource converter is given the image name so that the image can be referenced in an .Xde- 
faults file. Since an image can be referenced by a widget through its pixmap resources, it is up to 
the application to ensure that the image is installed before the widget is created. 

image Points to the image structure to be installed. The installation process does 

not make a local copy of the image. Therefore, the application should not 
destroy the image until it is uninstalled from the caching functions. 

imagejiame Specifies a string that the application uses to name the image. After installa- 

tion, this name can be used in .Xdefaults for referencing the image. A local 
copy of the name is created by the image caching functions. 

The image caching functions provide a set of eight preinstalled images. These names can be used 
within a .Xdefaults file for generating pixmaps for the resource for which they are provided. 



Image Name 


Description 


background 


A tile of solid background 


25_foreground 


A tile of 25% foreground, 75% background 


50_foreground 


A tile of 50% foreground, 50% background 


75 foreground 


A tile of 75% foreground, 25% background 


horizontal 


A tile of horizontal lines of the two colors 


vertical 


A tile of vertical lines of the two colors 


slant_right 


A tile of slanting lines of the two colors 


slant left 


A tile of slanting lines of the two colors 



RETURN VALUE 

Returns True when successful; returns False if a NULL image, NULL image name, or duplicate 
imagejiame are used as parameter values. 

RELATED INFORMATION 

XmUninstallImage(3X), XmGetPixmap(3X), and XmDestroyPixmap(3X). 
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NAME 

XmlnternAtom - a function that returns an atom for a given name. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/AtomMgr.h> 

Atom XmlnternAtom (display, name, onfy_if_exists) 
Display * display, 

String name; 
Boolean onty_if_exists; 

DESCRIPTION 

XmlnternAtom returns an atom for a given name. It mirrors the Xlib interfaces for atom manage- 
ment, but provides client-side caching. When and where caching is provided in Xlib, the routines 
will become pseudonyms for the Xlib routines. 

display Specifies the connection to the X server. 

name Specifies the name associated with the atom you want returned. 

ontyjfjpdsts Specifies a Boolean value that indicates whether XInternAtom creates the 

atom. 

RETURN VALUE 

Returns an atom. 
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NAME 

XmlsMotifWMRunning - a function that specifies if the window manager is running. 

SYNOPSIS 

# include <X11/Shell.h> 

Boolean XmlsMotifWMRunning (shell) 
Widget shell-, 

DESCRIPTION 

XmlsMotifWMRunning lets a user know if the OSF/Motif window manager is running on a 
screen that contains a specific widget hierarchy. This function first sees whether the 
MOTIF_WM_INFO property is present on the root window of the shell's screen. If it is, it's win- 
dow field is used to query for the presence of the specified window as a child of root. 

shell Specifies the shell whose screen will be tested for MWM's presence. 

RETURN VALUE 

Returns true if OSF/Motif window manager is running. 
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NAME 

XmLabel - the Label widget class. 

SYNOPSIS 

#include <Xm/Label.h> 

DESCRIPTION 

Label is an instantiable widget and is also used as a superclass for other button widgets, such as 
PushButton and ToggleButton. The Label widget does not accept any button or key input, and the 
help callback is the only callback defined. Label also receives enter and leave events. 

Label can contain either text or a pixmap. Label text is a compound string. Refer to the 
Programmer's Guide for more information on compound strings. The text can be multidirectional, 
multiline, and/or multifont. When a Label is insensitive, its text is stippled, or the user supplied 
insensitive pixmap is displayed. 

Label supports both accelerators and mnemonics primarily for use in Label subclass widgets that 
are contained in menus. Mnemonics are available in a menu system when the button is visible. 
Accelerators in a menu system are accessible even when the button is not visible. The Label 
widget displays the mnemonic by underlining the first matching character in the text string. The 
accelerator is displayed as a text string to the right of the label text or pixmap. 

Label consists of many margin fields surrounding the text or pixmap. These margin fields are 
resources that may be set by the user, but Label subclasses also modify some of these fields. The 
subclasses tend to modify the XmNmarginLeft, XmNmarginRight, XmNmarginTop, and 
XmNmarginBottom resources and leave the XmNmarginWidth and XmNmarginHeight resources 
as set by the application. 

Classes 

Label inherits behavior and resources from Core and XmPrimitive Classes. 
The class pointer is xmLabelWidgetClass. 
The class name is XmLabel. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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Xm Label Resource Set 


Name 


Class 


iyp« 


Default 


Access 


XmNaccelerator 


XmCAccelerator 


String 


NULL 


CSG 


XmNacceleratoiText 


XmCAcceleratorText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


0 


CSG 


YmNmarginHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


0 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


0 


CSG 


XmNmarginTop 


XmCMargjnTop 


short 


0 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


AO- 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 



XmNaccelerator 

Sets the accelerator on a button widget in a menu, which activates a visible or invisi- 
ble button from the keyboard. This resource is a string which describes a set of 
modifiers and the key which may be used to select the button. The format of this 
string is identical to that used by the translations manager, with the exception that 
only a single event may be specified and only KeyPress events are allowed. 

Accelerators for buttons are supported only for certain buttons in certain menu 
widgets, namely for PushButton and ToggleButton in Pulldown and Popup Menu- 
Panes. 

XmNacceleratoiText 

Specifies the text displayed for the accelerator. The text is displayed to the right of 
the label string or pixmap. Accelerator text for buttons is displayed only for Push- 
Buttons and ToggleButtons in Pulldown and Popup Menus. 

XmNalignment 

Specifies the label alignment for text or pixmap. 

• XmALIGNMENT_CENTER (center alignment) - causes the centers of the 
lines of text to be vertically aligned in the center of the widget window. For a 
pixmap, its center is vertically aligned with the center of the widget window. 

• XmALIGNMENT_END (right alignment) - causes the right sides of the lines of 
text to be vertically aligned with the right edge of the widget window. For a pix- 
map, its right side is vertically aligned with the right edge of the widget window. 

• XmALIGNMENT_BEGINNING (left alignment) - causes the left sides of the 
lines of text to be vertically aligned with the left edge of the widget window. For 
a pixmap, its left side is vertically aligned with the left edge of the widget win- 
dow. 

The above descriptions for text are correct when XmNstringDirection is 
XmSTRING DIRECTION L TO R. When that resource is 
XmSTRING"DIRECnON~R~TO_L, the descriptions for 

XmALIGNMENT BEGINNING and XmALIGNMENT END are switched. 

XmNfontList 

Specifies the font of the text used in the widget. Refer to XmFontListCreate(3X) 
for more information on the creation and the structure of a font list. 
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XmNlabellnsensitivePixmap 

Specifies a pixmap used as the button face if XmNlabelType is XmPIXMAP and the 
button is insensitive. 

XmNlabelPixmap 

Specifies the pixmap when XmNlabelType is XmPIXMAP. 

XmNlabelString 

Specifies the compound string when the XmNlabelTvpe is XmSTRING. Refer to 
XmStringCreate(3X) or XmStringCreateLtoR(3X) for more information on the 
creation and the structure of compound strings. 

XmNlabelType 

Specifies the label type. 

• XmSTRING - text displays XmNlabelString. 

• XmPIXMAP - icon data in pixmap displays XmNlabellnsensitivePixmap. 
XmNmarginBottom 

Specifies the amount of spacing that is to be left, after the bottom margin 
(XmNmarginHeight) of the widget, before the label is drawn. This maybe modified 
by Label's subclasses. For example, CascadeButton may increase this field to make 
room for the cascade pixmap. 

XmNmarginHeight 

Specifies the amount of blank space between the bottom edge of the top shadow 
and the label, and the top edge of the bottom shadow and the label. 

XmNmarginLeft 

Specifies the amount of spacing that is to be left, after the left margin (XmNmar- 
ginWidth) of the widget, before the label is drawn. This may be modified by Label's 
subclasses. For example, ToggleButton may increase this field to make room for 
the toggle indicator and for spacing between the indicator and label. 

XmNmarginRight 

Specifies the amount of spacing that is to be left, after the right margin (XmNmar- 
ginWidth) of the widget, before the label is drawn. This may be modified by Label's 
subclasses. For example, CascadeButton may increase this field to make room for 
the cascade pixmap. 

XmNmarginTop 

Specifies the amount of spacing that is to be left, after the top margin (XmNmar- 
ginHeight) of the widget, before the label is drawn. This may be modified by 
Label's subclasses. For example, CascadeButton may increase this field to make 
room for the cascade pixmap. 

XmNmarginWidth 

Specifies the amount of blank space between the right edge of the left shadow and 
the label, and the left edge of the right shadow and the label. 

XmNmnemonic 

Provides the user with alternate means for selecting a button. The buttons must be 
visible for mnemonics to work. Buttons, which are in either a MenuBar, a Popup 
MenuPane, or a Pulldown MenuPane, are allowed to have a mnemonic. 

This resource contains a single character. The first character in the label string that 
exactly matches the mnemonic is underlined when the button is displayed. 

When a mnemonic is specified for a MenuBar button, the user activates the 
mnemonic by pressing the meta key and the specified mnemonic key simultane- 
ously. All other mnemonics are activated by pressing the specified mnemonic. 
Mnemonics are case insensitive; the character underlined can be a modified key, 
but the key pressed should always be unmodified. 

XmNrecomputeSize 

Specifies a Boolean value that indicates whether or not the widget always attempts 
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to be big enough to contain the label. If True, an XtSetValues with a new label 
string or pixmap, accelerator text, margins, font, or label type causes the widget to 
shrink or expand to exactly fit the new label string or pixmap. If False, the widget 
never attempts to change size on its own. 

XmNstringDirection 

Specifies the direction in which the string is to be drawn. The following are the 
values: 

• XmSTRING DIRECTION L TO R - left to right. 

• XmSTRING DIRECTION R TO L - right to left. 



Inherited Resources 

Label inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShaoowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNMghhghtColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XrnNMghhgltfThickness 


XmCHighlightThickness 


short 


0 


CSG 


XmNshacJoWThickness 


XmCShadoWThickness 


short 


0 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPEXELS 


CSG 


XmNuserData 


XmCUserData 


caddrj 


NULL 


CSG 




Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNbadcgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNborderWidth 


XmCBorderWldth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadt 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWldth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 
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Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. For this callback, reason is set to 

XmCRHELP. 

event Points to the XEvent that triggered the callback. 

Default Translations 

<EnterWindow>: Enter() 
< LeaveWindow > : Leave() 

Keyboard Traversal 

For information on keyboard traversal, see the man page for XmPrimitive(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Core(3X), XmCreateLabel(3X), XmFontListCreate(3X), XmPrimitive(3X), XmString€reate(3X), 
and XmStringCreateLtoR(3X). 
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NAME 

XmLabelGadget - the LabelGadget widget class. 

SYNOPSIS 

#include <Xm/LabelG.h> 

DESCRIPTION 

LabelGadget is an instantiable widget and is also used as a superclass for other button gadgets, 
such as PushButtonGadget and ToggleButtonGadget The LabelGadget widget does not accept 
any button or key input, and the help callback is the only callback defined. LabelGadget also 
receives enter and leave events. 

LabelGadget can contain either text or a pixmap. LabelGadget text is a compound string. Refer 
to XmString for more information on compound strings. The text can be multidirectional, multi- 
line, and/or multifont When a LabelGadget is insensitive, its text is stippled, or the user supplied 
insensitive pixmap is displayed. 

LabelGadget supports both accelerators and mnemonics primarily for use in LabelGadget sub- 
class widgets that are contained in menus. Mnemonics are available in a menu system when the 
button is visible. Accelerators in a menu system are accessible even when the button is not visible. 
The LabelGadget displays the mnemonic by underlining the first matching character in the text 
string. The accelerator is displayed as a text string to the right of the label text or pixmap. 

LabelGadget consists of many margin fields surrounding the text or pixmap. These margin fields 
are resources that may be set by the user, but LabelGadget subclasses also modify some of these 
fields. The subclasses tend to modify the XmNmarginLeft, XmNmarginRight, XmNmarginTop, 
and XmNmarginBottom resources and leave the XmNmarginWidth and XmNmarginHeight 
resources as set by the application. 

Classes 

LabelGadget inherits behavior and resources from Object, RectObj and XmGadget classes. 
The class pointer is xmLabelGadgetClass. 
The class name is XmLabelGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmLabelGadget Resource Set 






Type 


Default 




XmNaccelerator 


XmCAooelcralor 


String 


NULL 


CSG 


XmNacceieratoiText 


XinCAcceleratorText 


XmString 


NULL 


CSG 


XmN alignment 


XmCAIignment 


unsigned char 


V« A T T^K114CKTP PCXJTCD 

XmAl<jKjINMI£N 1 Lcn 1 IsK 


CSG 


ajwn ionmsi 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnscnsitivcPixmap 


Pixmap 


V«»l TXJCDZ7/"<II7I17r\ DIVlf AD 

XniUNarcClrlElJ rlAMAr 


CSG 


VntXIInlulIKuMAn 

xmiN laDeirixmap 


XmCPixmap 


Pixmap 


V M T TKICPP/ '1 L.1 LJI \ DIV&iAD 

AmU N»r tll,lrll±0_r lAMAr 


CSG 


Amrs iaociocring 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabeTiypc 


XtnCLabeffype 


unsigned char 




CSG 


XmNmargmBottom 


XmCMargmBottom 


short 


0 


CSG 


XmNniarginHeight 


XmCM&rgmHcigbt 


snort 


2 


CSG 








o 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


0 


CSG 


XmNmarginTop 


XmCMargiriTop 


short 


0 


CSG 


XmNmarginWidth 


XmCMarginWdth 


short 


2 


CSG 


XmNmnemonic 


XmCMnemonic 


char 


'\0' 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirecticm 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 



XmNaccelerator 

Sets the accelerator on a button widget in a menu, which activates a visible or invisi- 
ble button from the keyboard. This resource is a string which describes a set of 
modifiers and the key which may be used to select the button. The format of this 
string is identical to that used by the translations manager, with the exception that 
only a single event may be specified and only KeyPress events are allowed. 

Accelerators for buttons are supported only for certain buttons in certain menu 
gadgets, namely for PushButtonGadget and ToggleButtonGadget in PullDown and 
Popup menus. 

XmNacceleratorText 

Specifies the text displayed for the accelerator. The text is displayed to the right of 
the label string or pixmap. Accelerator text for buttons is displayed only for Push- 
ButtonGadgets and ToggleButtonGadgets in Pulldown and Popup Menus. 

XmNalignment 

Specifies the label alignment for text or pixmap. 

• XmALIGNMENT_CENTER (center alignment) - causes the centers of the 
lines of text to be~vertically aligned in the center of the parent window. For a 
pixmap, its center is vertically aligned with the center of the widget window. 

• XmALIGNMENT_END (right alignment) - causes the right sides of the lines of 
text to be vertically aligned with the right edge of the parent window. For a pix- 
map, its right side is vertically aligned with the right edge of the widget window. 

• XmALIGNMENT_BEGINNING (left alignment) - causes the left sides of the 
lines of text to be vertically aligned with the left edge of the parent window. For 
a pixmap, its left side is vertically aligned with the left edge of the widget win- 
dow. 

The above descriptions for text are correct when XmNstringDirection is 
XmSTRING DIRECTION L TO R; the descriptions for 

XmALIGNMENT BEGINNING and XmALIGNMENT END are switched When 
the resource is XmSTRING DIRECTION R TO L. 

XmNfontList 

Specifies the font of the text used in the gadget. Refer to XmFontListCreate(3X) 
for more information on the creation and the structure of a font list 
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XmNlabellnsensitivePixmap 

Specifies a pixmap used as the button face if XmNIabelType is XmPIXMAP and the 
button is insensitive. 

XmNlabelPixmap 

Specifies the pixmap when XmNIabelType is XmPIXMAP. 

XmNIabelString 

Specifies the compound string when XmNIabelType is XmSTRING. R«fer to 
XmStringCreate(3X) or XmStringCreateLtoR(3X) for more information on the 
creation and the structure of compound strings. 

XmNIabelType 

Specifies the label type. 

• XmSTRING - text displays XmNIabelString. 

• XmPIXMAP - icon data in pixmap displays XmNlabelPixmap or XmNlabelln- 
sensitivePixmap. 

XmNmarginBottom 

Specifies the amount of spacing that is to be left, after the bottom margin 
(XmNmarginHeight) of the gadget, before the label is drawn. This may be 
modified by LabelGadget's subclasses. For example, CascadeButtonGadget may 
increase this field to make room for the cascade pixmap. 

XmNmarginHeight 

Specifies the amount of blank space between the bottom edge of the top shadow 
and the label, and the top edge of the bottom shadow and the label. 

XmNmarginLeft 

Specifies the amount of spacing that is to be left, after the left margin (XmNmar- 
ginWidth) of the gadget, before the label is drawn. This may be modified by 
LabelGadget's subclasses. For example, ToggleButtonGadget may increase this 
field to make room for the toggle indicator and for spacing between the indicator 
and label. 

XmNmarginRighi 

Specifies the amount of spacing that is to be left, after the right margin (XmNmar- 
ginWidth) of the gadget, before the label is drawn. This may be modified by 
LabelGadget's subclasses. For example, CascadeButtonGadget may increase this 
field to make room for the cascade pixmap. 

XmNmarginTop 

Specifies the amount of spacing that is to be left, after the top margin (XmNmar- 
ginHeight) of the gadget, before the label is drawn. This may be modified by 
LabelGadget's subclasses. For example, CascadeButtonGadget may increase this 
field to make room for the cascade pixmap. 

XmNmarginWidth 

Specifies the amount of blank space between the right edge of the left shadow and 
the label, and the left edge of the right shadow and the label. 

XmNmnemonic 

Provides the user with alternate means for selecting a button. The buttons must be 
visible for mnemonics to work. Buttons which are in either a Popup MenuPane, a 
Pulldown MenuPane, or an Option menu are allowed to have a mnemonic. 

This resource contains a single character. The first character in the label string that 
exactly matches the mnemonic is underlined when the button is displayed. 

Mnemonics are activated by pressing the specified mnemonic. Mnemonics are case 
insensitive; the character underlined can be a modified key, but the key pressed 
should always be unmodified. 

XmNrecomputeSize 

Specifies a Boolean value that indicates whether or not the gadget always attempts 
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to be big enough to contain the label. If True, an XtSetVahies with a new label 
string or pixmap, accelerator text, margins, font, or label type causes the gadget to 
shrink or expand to exactly fit the new label string or pixmap. If False, the gadget 
never attempts to change size on its own. 

XmNstringDirection 

Specifies the direction in which the string is to be drawn. The following are the 
values: 

• XmSTRING DIRECTION L TO R - left to right 

• XmSTRING DIRECTION R TO L - right to left. 

Inherited Resources 

LabelGadget inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmGadget Resource Set 


Name 


Class 


1>pe 


Default 


Access 


XmNhelpCallbadt 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightThickness 


XrnCHighHghrThickness 


short 


0 


CSG 


XmNshadowThickness 


XmCShadcwThidcness 


short 


0 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPrXELS 


CSG 


XmNuserData 


XmCUserData 


caddrj 


NULL 


CSG 



RectObj Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmGadget(3X) and its sections 
on behavior and default translations. 

RELATED INFORMATION 

Object (3X), RectObj (3X), XmCreateLabelGadget (3X) , XmFontListCreate(3X), XmGadget (3X), 
XmStringCreate(3X) , and XmStringCreateLtoR(3X). 
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NAME 

XmList - the List widget class. 

SYNOPSIS 

#include <Xm/List.h> 

DESCRIPTION 

List allows a user to select one or more items from a group of choices. Items are selected from 
the list in a variety of ways, using both the pointer and the keyboard. 

List operates on an array of strings that are defined by the application. Each string becomes an 
item in List, with the first string becoming the item in position 1, the second string becoming the 
item in position 2, and so on. 

The visual size of List is set by specifying the number of items that are visible. If selection scrol- 
ling ability through a large set of choices is desired, use the XmCreateScroIledList convenience 
function. 

To select items, move the pointer or cursor to the desired item and press the mouse button or the 
key defined as select. There are several styles of selection behavior, and they all highlight the 
selected item or items by displaying them in inverse colors. An appropriate callback is invoked to 
notify the application of the user's choice. The application then takes whatever action is required 
for the specified selection. 

Classes 

List inherits behavior and resources from Core and XmPrimitive classes. 
The class pointer is xmListWidgetClass. 
The class name is XmList. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmList Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNautomaticSelection 


XmCAutomaticSelection 


Boolean 


False 


CSG 


XmNbrovvseSelectionCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XinNdefaultActionCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNdoubleClicklntetval 


XmCDoubleClicklnterval 


int 


250 


CSG 


XmNextendedSelectionCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNfontList 


XmCFontList 


XmFontList 


"fixed" 


CSG 


XmNitemCount 


XmCItemCount 


int 


0 


CSG 


XmNitems 


XmCItems 


XmStriagTable 


NULL 


CSG 


XmNlistMarginHeight 


XmCListMarginHeight 


Dimension 


0 


CSG 


XmNlistMarginWidth 


XmCListMarginWidth 


Dimension 


0 


CSG 


XmNlistSpacing 


XmCListSpacing 


short 


0 


CSG 


XmNmultipleSelectionCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNselectedltemCount 


XmCSelectedltemCount 


int 


0 


CSG 


XmNselectedltems 


XmCSelectedltems 


XmStringTable 


NULL 


CSG 


XmNselectionPolicy 


XmCSelectionPolicy 


unsigned char 


XmBROWSE SELECT 


CSG 


XmNsingleSelectionCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 


XmNvisibleltemCount 


XmCVisibleltemCount 


int 


1 


CSG 



XmNautomaticSelection 

Invokes XmNsingleSelectionCallback when the user moves into a new item if the 
value is True and the selection mode is either XmBROWSE SELECT or 
XmEXTENDED_SELECT. If False, no selection callbacks invoke until the user 
releases the mouse button. See the Behavior section for further details on the 
interaction of this resource with the selection modes. 

XmNbrowseSelectionCallback 

Specifies a list of callbacks that is called when an item is selected in the browse 
selection mode. The reason is XmCRBROWSESELECT. 

XmNdefaultActionCallback 

Specifies a list of callbacks that is called when an item is double clicked. The reason 
is XmCRDEFAULTACTION. 

XmNdoubleClicklnterval 

Specifies the time in milliseconds that two consecutive clicks must occur within to be 
considered a double-click action, rather than two single-click actions. 

XmNextendedSelectionCallback 

Specifies a list of callbacks that is called when items are selected using the extended 
selection mode. The reason is XmCREXTENDEDSELECT. 

XmNfontList 

Specifies the font list associated with the list items. This is used in conjunction with 
the XmNvisibleltemsCount resource to determine the height of the List widget. 
Refer to XmString(3X) for more information on a font list structure. 

XmNitemCount 

Specifies the total number of items. This number must match XmNitems. It is 
automatically updated by the list whenever an element is added to or deleted from 
the list. 

XmNitems 

Points to an array of compound strings that are to be displayed as the list items. 
Refer to XmString(3X) for more information on the creation and structure of com- 
pound strings. 
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XmNlistMarginHeight 

Specifies the height of the margin between the List border and the items. 

XmNlistMarginWidth 

Specifies the width of the margin between the List border and the items. 

XmNlistSpacing 

Specifies the spacing between list items. When keyboard traversal is enabled, this 
spacing increases by the value of the XmNhighlightThickness parameter in Primi- 
tive. 

XmNmuItipleSelectionCallback 

Specifies a list of callbacks that is called when an item is selected in multiple selec- 
tion mode. The reason is XmCRMULTIPLESELECT. 

XmNselectedltemCount 

Specifies the number of strings in the selected items list. 

XmNselectedltems 

Points to an array of compound strings that represents the list items that are 
currently selected, either by the user or the application. 

XmN selectionPolicy 

Defines the interpretation of the selection action. This can be one of the following: 

• XmSINGLE_SELECT - allows only single selections. 

• XmMULTIPLE_SELECT - allows multiple selections. 

• XmEXTENDED_SELECT - allows extended selections. 

• XmBROWSE_SELECT - allows PM "drag and browse" functionality. 

XmNsingleSelectionCallback 

Specifies a list of callbacks that is called when an item is selected in single selection 
mode. The reason is XmCRSINGLESELECT. 

XmNstringDirection 

Specifies the initial direction to draw the string. The values are 
XmSTRINGDIRECTIONJLTOR and XmSTRING DIRECTION R TO L. 

XmNvisibleltemCount 

Specifies the number of items that can fit in the visible space of the List work area. 
The list will use this value to determine its height. 



XmScrolkdList Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhorizontalScrollBar 


XmCHorizontalScrollBar 


Widget 


NULL 


CSG 


XmNlistSizePolicy 


XmCListSizePolky 


unsigned char 


XmVARIABLE 


CG 


XmNscrollBarDisplayPolicy 


XmCScrollBarDispIayPolicy 


unsigned char 


XmAS NEEDED 


CSG 


XmNscrollBarPlacement 


XmCScrollBarPlacement 


unsigned char 


XmBOTTOM RIGHT 


CSG 


XmNscroUedWindowMarginHeight 


Xn^ScroUedWindtwMarginHeight 


Dimension 


0 


CSG 


XmNscroUedWindowMarginWldth 


XmCScrolledV»Oftd(»'MarginVv r idth 


Dimension 


0 


CSG 


XmNspacing 


XmCSpacing 


Dimension 


4 


CSG 


XmNverticalScrollBar 


XmCVerticalScrollBar 


Widget 


NULL 


CSG 



XmNhorizontalScrollBar 

Specifies the widget ID of the horizontal ScrollBar. This widget is created automat- 
ically by the XmCreateScroIledList convenience function. 

XmNlistSizePolicy 

Controls the reaction of the List when an item grows horizontally beyond the 
current size of the List work area. If the value is XmCONSTANT, the List viewing 
area will not grow, and a horizontal ScrollBar will be added. If this resource is set 
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to XmVARIABLE, List will grow to match the size of the longest item, and no hor- 
izontal ScrollBar will appear. 

When the value of this resource is XmRESIZE_IF_POSSIBLE, the List attempts to 
grow or shrink to match the width of the widesfitem. If it cannot grow to match the 
widest size, a horizontal ScrollBar is added if the longest item is wider than the List 
viewing area. 

The size policy must be set at the time the List widget is created. It cannot be 
changed at a later time through XtSetValues. 

XmNscroUBarDisplayPolicy 

Specifies the ScrollBar display policy. When this resource is set to 
XmAS_NEEDED, the vertical ScrollBar will be displayed only when the number of 
items in the list exceeds the number of visible items. If XmNIistSizePolicy is 
XmCONSTANT or XmRESIZE_IF_POSSIBLE, the horizontal ScrollBar will be 
displayed only if there is an item that is wider than the current width of the list 
When this resource is set to Xm STATIC, the vertical ScrollBar will always be 
displayed. The horizontal ScrollBar will always be displayed if XmNIistSizePolicy is 
set to XmCONSTANT or XmRESIZE IF POSSIBLE. 

XmNscrollBarPlacement 

Specifies the positioning of the ScrollBars in relation to the visible items. The fol- 
lowing are the values: 

• XmTOP_LEFT - The horizontal ScrollBar is placed above the visible items and 
the vertical ScrollBar to the left of the visible items. 

• XmBOTTOM_LEFT - The horizontal ScrollBar is placed below the visible 
items and the vertical ScrollBar to the left of the visible items. 

• XmTOP_RIGHT - The horizontal ScrollBar is placed above the visible items 
and the vertical ScrollBar to the right of the visible items. 

• XmBOTTOM RIGHT - The horizontal ScrollBar is placed below the visible 
items and the vertical ScrollBar to the right of the visible items. 

XmNscroUedWindowMarginHeight 

Specifies the margin height on the top and bottom of the ScrolledWindow. 

XmNscrolledWindowMarginWidth 

Specifies the margin width on the right and left sides of the ScrolledWindow. 

XmNspacing 

Specifies the distance that separates the ScrollBars from the visible items. 

XmNverticalScroIlBar 

Specifies the widget ID of the vertical ScrollBar. This widget is created automati- 
cally by the XmCreateScrolledList convenience function. 

Inherited Resources 

List inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 
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XmPrimitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIEDJPDCMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNMghlightThickness 


XmCHighlightThickness 


snort 


0 


CSG 


XmNshadowThiclcness 


XmCShadoWThickness 


short 


2 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 




Core Resource Set 


Name 


Class 


TV"* 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepCh 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCaUback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

List defines a new callback structure. The application must first look at the reason field and 
only use the structure members that are valid for that particular reason, because not all of 
the fields are relevant for every possible reason. The callback structure is defined as fol- 
lows: 
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typedef struct 
{ 

int 

XEvent 
XmString 
int 
int 

XmString 

int 

int 

} XmListCallbackStruct; 



reason; 

* event; 
item; 

itemjength; 
item _position; 

* selected Jtems; 
selected Jtem count, 
selection jype; 



reason 
event 



item 



Indicates why the callback was invoked. 

Points to the XEvent that triggered the callback. It can be 
NULL. 

Is the item selected by this action, selected jtems points to a 
temporary storage space that is reused after the callback is 
finished. Therefore, if an application needs to save the selected 
list, it should copy the list into its own data space. 

Is the length of the item when the selection action occurred. 

Is the position in the List of the selected item. 

Points to the list of items selected at the time of the event that 
caused the callback, selected jtems points to a temporary 
storage space that is reused after the callback is finished. 
Therefore, if an application needs to save the selected list, it 
should copy the list into its own data space. 

Is the number of items in the selected jtems list. 

Indicates that the most recent extended selection was either the 
initial selection (XmlNITIAL), a modification of an existing 
selection (XmMODIFICATION), or an additional noncontigu- 
ous selection (XmADDITION). 

The following table describes the reasons for which the individual callback structure fields 
are valid: 



itemjength 
item _position 
selected items 



selected jtems _count 
selection jype 



Reason 


Valid Fields 


XmCR SINGLE SELECT 


reason, event, item, item length, item _position 


XmCR DEFAULT ACTION 


reason, event, item, itemjength, item jposition 


XmCR BROWSE SELECT 


reason, event, item, item length, item _position 


XmCR MULTIPLE SELECT 


reason, event, item, selected items, 
selected item count 


XmCREXTENDEDSELECT 


reason, event, item, selected jtems, 
selected jtem _count, selection jype 



Behavior 

List provides several methods for selecting its items. The general selection model is as fol- 
lows: 

The user moves the pointer to the item that is desired to be selected, either by using the 
mouse to move the pointer over the desired item, or, in keyboard traversal mode, moving 
the active highlight to the desired item with the up and down arrow keys. The item is 
selected by clicking the select button on the mouse (usually the left mouse button), or by 
pressing the select key on the keyboard (usually defined to be the Space key). Each of the 
selection modes provides some variation of the above behavior. 
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Note that the keyboard selection interface is only active when traversal is enabled for the 
List widget. 

The selection mode is set by the XmNselectionPolicy resource and is modified by the 
XmNautomaticSelection resource. The behavior of the various modes are defined below: 

XmSINGLESELECT (Single Selection): 

Move the mouse pointer or keyboard highlight until it is over the desired item and 
press the select button or key. The item inverts its foreground and background 
colors to indicate that it is to be the selected object Any previously selected items 
are unselected (returned to their normal visual state). When the button or key is 
released, XmNsingleSelectionCallback is invoked. 

XmBROWSESELECT (Browse Selection): 

When using the mouse, press the select button; the item under the pointer is 
highlighted. While the button is held down, drag the selection by moving the 
pointer. When the select button is released, the object under the pointer becomes 
the selected item and the XmNbrowseSelectionCallback is invoked. 

If XmNautomaticSelection is True, the XmNbrowseSelectionCallback is invoked 
when the select button is pressed. For each subsequent item entered while the 
select button is held down, the callback is invoked when the pointer moves into the 
item. No selection callback is invoked when the button is released. 

When selecting through the keyboard and XmNautomaticSelection is False, browse 
selection is no different from single-selection mode. However, when XmNautoma- 
ticSelection is True, the callback is invoked for each element that is selected. Both 
the keyboard highlight and the selection highlight move as the user moves through 
the list. 

XmMULTIPLE SELECT (Multiple Selection): 

Move the mouse pointer or keyboard highlight until it is over the desired item and 
press the select button or key. The item inverts its foreground and background 
colors to indicate that it is a selected object. Any previously selected items are not 
affected by this action. When the button or key is released, the XmNmultipleSelec- 
tionCallback is invoked. To unselect an item in this mode, move to a selected item 
and press the select button or key. The XmNmultipleSelectionCallback is invoked 
with the updated selection list. 

XmEXTENDEDSELECT (Extended Selection): 

This mode selects a contiguous range of objects with one action. Press the select 
button on the first item of the range. This begins a new selection process, which 
deselects any previous selection in the list. That item inverts to show its inclusion in 
the selection. While depressing the button, drag the cursor through other items in 
the List. As the pointer moves through the list, all items between the initial item and 
the item currently under the pointer are inverted to show that they are included in 
the selection. When the button is released, the XmNextendedSelectionCallback is 
invoked and contains a list of all selected items. The selection Jype field is set to 
XmlNITIAL. 

Modify a selection by pressing and holding the shift key, moving to the new end- 
point, and pressing the select button. The items between the initial start point and 
the new end point are selected. The rest of the selection process proceeds as above. 
Any previous selections are not unselected. When the select button is released, the 
XmNextendedSelectionCallback is invoked and contains a list of all selected items, 
both new and previous. The selection Jype field is to XmMODIFICATION. 

Items can be added to or deleted from a selected range by using the CTRL key. To 
add an additional range to an existing selection, move to the first item of the new 
group, press and hold the CTRL key, and then press the select button. The item 
under the pointer inverts; any previous selections are unaffected. This item becomes 
the initial item for the new selection range. If the pointer is dragged through addi- 
tional items while the CTRL key and select button are held down, those items invert 
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as described above. When the select button is released, the XmNextended Selection- 
Callback is invoked and contains a list of all selected items, both new and previous. 
The selection jype field is set to XmADDITION. 

To delete an item or a range of items from an existing selection, move to the first 
item to be deselected, press and hold the CTRL key, and then press the select but- 
ton. The item under the pointer returns to its normal visual state to indicate that it 
is no longer in the selection. This item becomes the initial item for the range to be 
deselected. If the pointer is dragged through additional selected items while the 
CTRL key and select button are held down, those items will be deselected. Any 
other selections are unaffected. When the select button is released, the XmNexten- 
dedSelectionCallback is invoked and contains a list of remaining selected items, 
both new and previous. The selection Jype field is set to XmADDITION. 

A range of items can also be deselected by setting the initial item for the range as 
described above, then moving to the end of the range, and pressing the select button 
while holding the Shift key down. All items between the two endpoints will be 
deselected. When the button is released, the XmNextendedSelectionCallback will be 
issued as described above. 

If the XmNautomaticSelection resource is set to True, the XmNextendedSelection- 
Callback is invoked when the select button is pressed. For each subsequent item 
the user selects or deselects, the callback is invoked when the pointer is moved into 
the item. The selection jype field is set to reflect the current action. No selection 
callback is invoked when the button is released. 

Keyboard selection in extended selection mode is accomplished by moving the key- 
board highlight to the start of the desired range and pressing the select key. The 
selection callback is invoked with a selection Jype value of XmlNITIAL. Then, using 
the arrow keys, move the keyboard highlight to the end of the range, depress the 
Shift key, and press the select key. The XmNextendedSelectionCallback is invoked 
with a value of XmMODIFICATTON. Select additional ranges by moving to the 
beginning of a range, pressing the select key while depressing the CTRL key, and 
then moving to the end of the range and pressing the select key while holding the 
Shift key. Erase previously selected elements by moving to them and pressing the 
select key while holding down the CTRL key. In all cases, callbacks are issued as 
described above. 

When using the keyboard with the XmNautomaticSelection resource set to True, 
the XmNextendedSelectionCallback is invoked when the select button is pressed. 
For each subsequent item the user selects, the callback is invoked when the pointer 
is moved into the item if there are modifier keys in use. For example, start the 
selection by pressing the select key, and then extend it by using the arrow keys while 
holding down the Shift key. The selection Jype field is set to reflect the current 
action. There is no selection callback invoked when the button is released. 

XmDEFAULT-ACTION (Double Click) 

If an object is clicked twice within the interval defined by the XmNdoubleClicklnter- 
val resource, the List interprets that as a double click and the XmNdefaultAction- 
Callback is invoked. The item inverts to indicate its selection. 

Default Translations 

The following are the default translations for List: 

Buttonl<Motion>: 
Shift Ctrl ~Meta<BtnlDown>: 
Shift Ctrl Meta<BtnlUp>: 
Shift Ctrl "Meta<KeyDown> space: 
Shift Ctrl 'Meta<KeyUp>spac« 
Shift Ctrl 'Meta<KeyDown> Select: 
Shift Ctrl "Meta<KeyUp> Select: 



ListButtonMotion() 

ListShiftCtrlSelectO 

ListShiftCtrlUnSelectO 

ListKbdShiftCtrlSelectO 

ListKbdShiftCtrlUnSelectO 

ListKbdShiftCtrlSelectO 

ListKbdShiftCtrlUnSelectO 
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Shift "Ctrl "Meta<BtnlDown>: 
Shift Ctrl Meta <BtnlUp>: 
Shift "Ctrl "Meta <KeyDown> space 
Shift "Ctrl "Meta<KeyUp>space: 
Shift "Ctrl "Meta<KeyDown>Select: 
Shift "Ctrl "Meta<KeyUp> Select: 
Ctrl 'Shift "Meta<BinlDown>: 
Ctrl "Shift "Meta<BtnlUp>: 
Ctrl "Shift " Meta < KeyDown > space: 
Ctrl "Shift "Meta <KeyUp> space: 
Ctrl 'Shift "Meta <KeyDown> Select: 
Ctrl 'Shift "Meta <KeyUp> Select: 
'Shift 'Ctrl "Meta<BtnlDown>: 
'Shift "Ctrl "Meta<BtnlUp>: 
"Shift 'Ctrl " Meta < KeyDown > space: 
"Shift 'Ctrl "Meta <KeyUp> space: 
'Shift "Ctrl 'Meta<KeyDown>SeIect: 
"Shift 'Ctrl " Meta <KeyUp> Select: 
Shift Ctrl "Meta<Key>Up: 
Shift Ctrl ' Meta < Key > Down: 
Shift 'Ctrl 'Meta<Key>Up: 
Shift "Ctrl " Meta < Key > Down: 
"Shift Ctrl "Meta<Key>Up: 
"Shift Ctrl 'Meta<Key>Dowrc 
"Shift 'Ctrl "Meta<Key>Up: 
"Shift 'Ctrl " Meta < Key > Down: 
<Enter>: 

< Leave >: 
<FocusIn>: 
<FocusOut>: 
<Unmap>: 
Shift < Key >Tab: 
<Key>Tab: 
Ctrl<Key>Tab: 

< Key > Home: 



ListShiftSelectO 

ListShiftUnSelectO 

ListKbdShiftSelectO 

ListKbdShiftUnSelectO 

ListKbdShiftSelectO 

ListKbdShiftUnSelectO 

ListCtrlSelect() 

ListCtrlUnSelectO 

ListKbdCtrlSelectO 

ListKbdCtrlUnSelectO 

ListKbdCtrlSelectO 

ListKbdCtrlUnSelectO 

ListElementSelectO 

ListElementUnSelect() 

ListKbdSelect() 

ListKbdUnSelect() 

ListKbdSelect() 

ListKbdUnSelectO 

ListShiftCtrU?revElement() 

ListShiftCtrlNextElementO 

ListShiftPrevElementO 

ListShiftNextElementO 

ListCtrlPrevElement() 

ListCtrlNextElementO 

ListPrevElementO 

ListNextElementO 

ListEnter() 

ListLeave() 

ListFocusIn() 

ListFocusOut() 

PrimitiveUnmapO 

PrimitivePrevTabGroupO 

PrimitiveNextTabGroupO 

PrimitiveNextTabGroupO 

PrimitiveTraverseHomeO 



Keyboard Traversal 

For those actions not inherited from XmPrimitive(3X), keyboard traversal is described in 
the behavior section of this man page. 



RELATED INFORMATION 

Core(3X), XmCreateList(3X), XmCreateScroUedList(3X), XmFontListCreate(3X) 
XmListAddItem(3X), XmListAddItemUnseIected(3X), XmListDeleteItem(3X), 
XmListDeletePos(3X),XmListDeselectItem(3X),XmListDeselectAUItems(3X), 
XmListSeIectItem(3X), XmListSetHorizPos(3X), XmListSetItem(3X), XmListSetPos(3X), 
XmListSetBottomItem(3X), XmListSetBottomPos(3X), XmListSelectPos(3X), 
XmListDeselectPos(3X), and XmListItemExists(3X), XmPrimitive(3X), and XmStringCreate(3X). 
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NAME 

XmListAddltem - a List function that adds an item to the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListAddltem (widget, item, position) 



XmListAddltem adds an item to the list at the given position. The position specifies the location 
of the new item in the list Position 1 is the first element, position 2 is the second, and so on. If 
the position argument is zero, the item is added after the last item in the list. When the item is 
inserted into the list, it is compared against the current XmNselectedltems list If the new item 
matches an item on the selected list, it appears selected. 

widget Specifies the ID of the List from whose list an item is added. 

item Specifies the item to be added to the list 

position Specifies the placement of the item within the list in terms of its cell position. It 



uses an insert mode/cell number scheme with a 1 specifying the top-entry position 
and a zero specifying the bottom entry for adding an item to the bottom of the list. 



For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 



Widget 
XmString 
int 



widget; 
item; 
position; 



DESCRIPTION 
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NAME 

XmListAddltemUnselected - a List function that adds an item to the list. 



SYNOPSIS 

#include <Xm/Listh> 

void XmListAddltemUnselected (widget, item, position) 
Widget widget; 
XmString item; 
int position; 

DESCRIPTION 

XmListAddltemUnselected adds an item to the list at the given position. The position specifies the 
location of the new item in the list Position 1 is the first element, position 2 is the second, and so 
on. If the position argument is zero, the item is added after the last item in the list 

widget Specifies the ID of the List from whose list an item is added. 

item Specifies the item to be added to the list 

position Specifies the placement of the item within the list in terms of its cell position. It 

uses an insert mode/cell number scheme with a 1 specifying the top-entry position 
and a zero specifying the bottom entry for adding an item to the bottom of the list 

For a complete definition of List and its associated resources, see XmList(3X). 



RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListDekteltem - a List function that deletes an item from the list. 



SYNOPSIS 

#include <Xm/List.h> 

void XmListDeleteltem (widget, item) 
Widget widget; 
XmString item; 

DESCRIPTION 

XmListDeleteltem deletes a specified item from the list. A warning message displays if the item 
does not exist 

widget Specifies the ID of the List from whose list an item is added. 

item Specifies the text of the item to be added to the list. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListDektePos - a List function that deletes an item from a list at a specified position. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListDeletePos (widget, position) 
Widget widget; 
int position; 

DESCRIPTION 

XmListDeletePos deletes an item at a specified position. A position argument of zero deletes the 
last item in the list. A warning message displays if the position does not exist. 

widget Specifies the ID of the List from whose list an item is added. 

position Identifies the position of the item to be deleted. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListDeselectAlUtems - a List function that unhighlights and removes all items from the 
selected list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListDeselectAlUtems (widget, item) 
Widget widget; 

DESCRIPTION 

XmListDeselectAlUtems unhighlights and removes all items from the selected list. 

widget Specifies the ID of the List widget from whose list all selected items are 

deselected. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListDeselectltem - a List function that deselects the specified item from the selected list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListDeselectltem (widget, item) 
Widget widget; 
XmString item; 

DESCRIPTION 

XmListDeselectltem unhighlights and removes the specified item from the selected list. 

widget Specifies the ID of the List from whose list an item is deselected. 

item Specifies the item to be deselected from the list. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListDeselectPos - a List function that deselects an item at a specified position in the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListDeselectPos (widget, position) 
Widget widget; 
int position; 

DESCRIPTION 

XmListDeselectPos unhighlights the item at the specified position and deletes it from the selected 
list. 

widget Specifies the ID of the List widget 

position Identifies the specified position. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListltemExists - a List function that checks if a specified item is in the list. 

SYNOPSIS 

#include <Xm/ListJi> 

Boolean XmListltemExists (widget, item) 
Widget widget; 
XmString item; 

DESCRIPTION 

XmListltemExists is a Boolean function that checks if a specified item is present in the list. 

widget Specifies the ID of the List widget. 

item Specifies the the given item. 

For a complete definition of List and its associated resources, see XmList(3X). 

RETURN VALUE 

Returns True if the specified item is present in the list. 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListSelectltem - a List function that selects an item in the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSelectltem (widget, item, notify) 
Widget widget; 
XmString item; 
Boolean notify; 

DESCRIPTION 

XmListSelectltem highlights and adds the specified item to the current selected list. 

widget Specifies the ID of the List widget from whose list an item is selected. 

item Specifies the item to be added to the List widget 

notify Specifies a Boolean value that when True invokes the selection callback for the 

current mode. From an application interface view, calling this function with notify 
True is indistinguishable from a user-initiated selection action. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELAXED INFORMATION 
XmList(3X). 
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NAME 

XmListSelectPos - a List function that selects an item at a specified position in the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSelectPos (widget, position, notify) 
Widget widget; 
bit position; 
Boolean notify; 

DESCRIPTION 

XmListSelectPos highlights an item at the specified position and adds it to the current selected 
list. A position of zero specifies the last item in the list. 

widget Specifies the ID of the List widget. 

position Identifies the specified position. 

notify Specifies a Boolean value that when True invokes the selection callback for the 

current mode. From an application interface view, calling this function with notify 
True is indistinguishable from a user-initiated selection action. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELAXED INFORMATION 
XmList(3X). 
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NAME 

XmListSetBottomltem - a List function that makes an existing item the last visible item in the 
list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSetBottomltem (widget, item) 
Widget widget; 
XmString item; 

DESCRIPTION 

XmListSetBottomltem makes an existing item the last visible item in the list. The item can be any 
valid item in the list 

widget Specifies the ID of the List widget from whose list an item is made the last visible. 

item Specifies the given item. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListSetBottomPos - a List function that makes a specified item the last visible position in the 
list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSetBottomPos (widget, position) 
Widget widget; 
int position; 

DESCRIPTION 

XmListSetBottomPos makes a given item the last visible position in the list. The position can be 
any valid position in the list. A position of 0 specifies the last item in the list 

widget Specifies the ID of the List widget. 

position Identifies the specified position. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListSetHorizPos - a List function that moves a ScrollBar to the specified position in the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSetHorizPos (widget, position) 
Widget widget; 
int position; 

DESCRIPTION 

XmListSetHorizPos sets the XmNvalue resource of the ScrollBar to the specified position and 
updates the visible portion of the list with the new value if the List widget's XmNIistSizePolicy is 
set to XmCONSTANT or XmRESIZE_IF_POSSIBLE and the horizontal ScrollBar is currently 
visible. This is equivalent to moving the ScrollBar to the specified position. 

widget Specifies the ID of the List widget. 

position Identifies the specified position. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListSetltem - a List Amotion that makes an existing item the first visible item in the list.. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSetltem (widget, item) 

Widget widget; 
XmString item; 

DESCRIPTION 

XmListSetltem makes an existing item the first visible item in the list. The item can be any valid 
item in the list. 

widget Specifies the ID of the List widget from whose list an item is made the first visible. 

item Specifies the given item. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmListSetPos - a List function that makes the item at the given position the first visible position 
in the list. 

SYNOPSIS 

#include <Xm/List.h> 

void XmListSetPos (widget, position) 
Widget widget, 
int position; 

DESCRIPTION 

XmListSetPos makes the item at the given position the first visible position in the list. The posi- 
tion can be any valid position in the list. 

widget Specifies the ID of the List widget. 

position Identifies the specified position. 

For a complete definition of List and its associated resources, see XmList(3X). 

RELATED INFORMATION 
XmList(3X). 
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NAME 

XmMainWindow - the MainWindow widget class. 

SYNOPSIS 

#include <Xm/MainW.h> 

DESCRIPTION 

MainWindow provides a standard layout for the primary window of an application. This layout 
includes a MenuBar, a CommandWindow, a work region, and ScrollBars. Any or all of these 
areas are optional. The work region and ScrollBars in the MainWindow behave identically to the 
work region and ScrollBars in the ScrolledWindow widget. The user can think of the MainWin- 
dow as an extended ScrolledWindow with an optional MenuBar and optional CommandWindow. 

In a fully-loaded MainWindow, the MenuBar spans the top of the window horizontally. The Com- 
mandWindow spans the MainWindow horizontally just below the MenuBar, and the work region 
lies below the CommandWindow. The space remaining below the CommandWindow, if any, is 
managed in a manner identical to ScrolledWindow. The behavior of ScrolledWindow can be con- 
trolled by the ScrolledWindow resources. To create a MainWindow, first create a MenuBar, a 
CommandWindow, a horizontal ScrollBar, and a vertical ScrollBar widget to use as the work 
region, and then call XmMainWindowSetAreas with those widget IDs. 

MainWindow can also create two Separator widgets that provide a visual separation of 
MainWindow's three components. 

Classes 

MainWindow inherits behavior and resources from Core, Composite, Constraint, 
XmManager, and ScrolledWindow classes. 

The class pointer is xmMainWindowWidgetClass. 

The class name is XmMainWindow. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmMainWindow Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNcommandWindow 


XinCCommandWindcw 


Widget 


NULL 


CSG 


XmNmainWindcwMarginHeight 


XinCMainWindowMarginHeight 


Dimension 


0 


CSG 


XmNmainWindowMarginWidth 


XmCMainWiretowMarginWidth 


Dimension 


0 


CSG 


XmNmenuBar 


XmCMenuBar 


Widget 


NULL 


CSG 


XmNshowSeparator 


XmCShowSeparator 


Boolean 


False 


CSG 



XmNcommandWindow 

Specifies the widget to be laid out as the CommandWindow. This widget must have 
been previously created and managed as a child of MainWindow. 

XmNmainWindowMarginHeight 

Specifies the margin height on the top and bottom of MainWindow. This resource 
overrides any setting of the ScrolledWindow resource XmNscroIledWindowMar- 
ginHeight. 
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XmNmainWindowMarginWidth 

Specifies the margin width on the right and left sides of MainWindow. This 
resource overrides any setting of the ScrolledWindow resource XmN scrolled Win- 
dowMarginWidth. 

XmNmenuBar 

Specifies the widget to be laid out as the MenuBar. This widget must have been 
previously created and managed as a child of MainWindow. 

XmNshowSeparator 

Displays separators between the components of the MainWindow when set to true. 
If set to False, no separators are displayed. 



Inherited Resources 

MainWindow inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmScrolledWindow Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdipWindow 


XmCClipWindcw 


widget 


NULL 


G 


XmNhorizontalScrollBar 


XmCHorizontalScrollBar 


Widget 


NULL 


CSG 


XmNscrollBarDisplayPolicy 


XmCScrollBarDisplayPolicy 


unsigned char 


XmSTATIC 


CG 


XmNscrollBarPlacement 


XmCScrollBarPlacement 


unsigned char 


XmBOTTOM RIGHT 


CSG 


XmNscroUedWrakwMarginHeight 


XmCScrolledWiiKtawMarginHeighl 


Dimension 


0 


CSG 


XinNscroUedWindowMarginWidth 


XmCScrolledWindowMarginWidth 


Dimension 


0 


CSG 


XmNscrollingPolky 


XmCScrollingPolicy 


unsigned char 


XmAPPLICATION_DEFINED 


CG 


XmNspacing 


XmCSpacing 


int 


4 


CSG 


XmNverticalScrollBar 


XmCVeiticalScrollBar 


Widget 


NULL 


CSG 


XmNvisualPolicy 


XmCVisualPolicy 


unsigned char 


XmVARIABLE 


CG 


XmNworkWmdow 


XmCWorkWindow 


Widget 


NULL 


CSG 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadoWThidcness 


XmCShadoWThickness 


short 


0 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED_PDCMAP 


CSG 


XmNunitType 


XmCUnifType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmN accelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadc 


XmCCallbadc 


XtCallbadcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

MainWindow inherits behavior from ScrolledWindow. 
Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 

RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateMainWindow(3X), 
XmMainWindowSepl(3X), XmMainWindowSep2(3X), XmMainWindowSetAreas(3X), 
XmManager(3X), and XmScrolIed Window(3X) , 
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NAME 

XmMainWindowSepl - a MainWindow function that returns the widget ID of the first Separator 
widget. 

SYNOPSIS 

#include <Xm/MainW.h> 

Widget XmMainWindowSepl (widget) 
Widget widget, 

DESCRIPTION 

XmMainWindowSepl returns the widget ID of the first Separator widget in the MainWindow. 
The first Separator widget is located between the MenuBar and the Command widget. This 
Separator is visible only when XmNshowSeparator is True. 

widget Specifies the MainWindow widget ID. 

For a complete definition of MainWindow and its associated resources, see XmMainWindow(3X). 

RETURN VALUE 

Returns the widget ID of the first Separator. 

RELATED INFORMATION 

XmMainWindow(3X). 
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NAME 

XmMainWindowSep2 - a MainWindow function that returns the widget ID of the second Separa- 
tor widget. 

SYNOPSIS 

#include <Xm/MainW.h> 

Widget XmMainWindowSep2 (widget) 

Widget widget; 

DESCRIPTION 

XmMainWindowSep2 returns the widget ID of the second Separator widget in the MainWindow. 
The second Separator widget is located between the Command widget and the ScrolledWindow. 
This Separator is visible only when XmNshowSeparator is True. 

widget Specifies the MainWindow widget ID. 

For a complete definition of MainWindow and its associated resources, see XmMainWindow(3X). 



RETURN VALUE 

Returns the widget ID of the second Separator. 



RELATED INFORMATION 

XmMainWindow(3X). 
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NAME 

XmMainWindowSetAreas - a MainWindow function that identifies manageable children for each 
area. 



SYNOPSIS 

#include <Xm/MainW.h> 

void XmMainWindowSetAreas (widget, menubar, command jvindow, horizontal jcrollbar, 

vertical scrollbar, workjegion) 

Widget widget; 
Widget menu_bar, 
Widget command jvindow, 
Widget horizontal scrollbar, 

Widget vertical jcrollbar, 
Widget workjegion; 



DESCRIPTION 

XmMainWindowSetAreas identifies which of the valid children for each area (MenuBar, work 
region, etc.) are to be actively managed by MainWindow. This function also sets up or adds the 
MenuBar, work window, command window, and ScrollBar widgets to the application's main win- 
dow widget. 

Each area is optional; therefore, the user can pass NULL to one or more of the following argu- 
ments. The window manager provides the title bar. 



widget 
menu bar 



command window 



horizontal scrollbar 



vertical scrollbar 



workjegion 



Specifies the MainWindow widget ID. 

Specifies the widget ID for the MenuBar to be associated with the 
MainWindow widget Set this ID only after creating an instance of the 
MainWindow widget. The attribute name associated with this argu- 
ment is XmNmenuBar. 

Specifies the widget ID for the command window to be associated with 
the MainWindow widget. Set this ID only after creating an instance of 
the MainWindow widget. The attribute name associated with this argu- 
ment is XmNcommand Window. 

Specifies the ScrollBar widget ID for the horizontal ScrollBar to be 
associated with the MainWindow widget. Set this ID only after creating 
an instance of the MainWindow widget. The attribute name associated 
with this argument is XmNhorizontalScrolIBar. 

Specifies the ScrollBar widget ID for the vertical ScrollBar to be associ- 
ated with the MainWindow widget Set this ID only after creating an 
instance of the MainWindow widget The attribute name associated 
with this argument is XmNverticalScrollBar. 

Specifies the widget ID for the work window to be associated with the 
MainWindow widget. Set this ID only after creating an instance of the 
MainWindow widget. The attribute name associated with this argu- 
ment is XmNworkWindow. 



For a complete definition of MainWindow and its associated resources, see XmMainWindow(3X). 



RELATED INFORMATION 

XmMainWindow(3X). 
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NAME 

XmManager - the Manager widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Manager is a widget class used as a supporting superclass for other widget classes. It supports the 
visual resources, graphics contexts, and traversal resources necessary for the graphics and traversal 
mechanisms. 

Classes 

Manager inherits behavior and resources from Core Composite, and Constraint classes. 
The class pointer is xmManagerWidgetClass. 
The class name is XmManager. 
New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmManager Resource Set 


Name 


Class 


^pe 


Default 


Access 


XmNbottomShadcPwColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadcwPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCaUbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadowThickness 


XmCShadoWThickness 


short 


0 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNunifPype 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



XmNbottomShadowColor 

Specifies the color to use to draw the bottom and right sides of the border shadow. 
This color is used if the XmNbottomShadowPixmap resource is NULL. 

XmNbottomShadowPixmap 

Specifies the pixmap to use to draw the bottom and right sides of the border sha- 
dow. 

XmNforeground 

Specifies the foreground drawing color used by manager widgets. 

XmNhelpCallback 

Specifies the list of callbacks that are called when the help key sequence is pressed. 
The reason sent by this callback is XmCR HELP. There is not a translation bound 
to this resource. It is up to the application to install a translation for help. 



Hewlett-Packard Company 



-1- 



Aug28, 1989 



XmManager(3X) 



XmManager(3X) 



XmNhighlightColor 

Specifies the color of the highlighting rectangle. This color is used if the highlight 
pixmap resource is XmUNSPECIFIED PIXMAP. 

XmNhighlightPixmap 

Specifies the pixmap used to draw the highlighting rectangle. 

XmNshadowThickness 

Specifies the thickness of the drawn border shadow. 

XmNtopShadowColor 

Specifies the color to use to draw the top and left sides of the border shadow. This 
color is used if the XmNtopShadowPixmap resource is NULL. 

XmNtopShadowPixmap 

Specifies the pixmap to use to draw the top and left sides of the border shadow. 

XmNunitType 

Provides the basic support for resolution independence. It defines the type of units 
a widget will use with sizing and positioning resources. Unless the XmNunitType 
resource is explicitly set, it will default to the unit type of the parent widget. If the 
parent has a unit type of XmlOOTH POINTS, men any of its children whose 
XmNunitType resource is not set will also have a unit type of XmlOOTH POINTS. 
This feature applies only to widgets whose parents are a subclass of XmManager. 
Widgets whose parents are not subclasses of XmManager will have a unit type of 
XmPIXELS. 

XmNunitType can have the following values: 

• XmPIXELS - all values provided to the widget are treated as normal pixel 
values. This is the default for the resource. 

• XmlOOTH MILLIMETERS - all values provided to the widget are treated as 
1/100 millimeter. 

• Xml000TH_INCHES - all values provided to the widget are treated as 1/1000 
inch. 

• XmlOOTHPOINTS - all values provided to the widget are treated as 1/100 
point. A point is a unit typically used in text processing applications and is 
defined as 1/72 inch. 

• XmlOOTH FONT UNITS - all values provided to the widget are treated as 
1/100-font unit. The value to be used for the font unit is determined in one of 
two ways. The resource XmNfont can be used in a defaults file or on the com- 
mand line. The standard command line options of -fn and -font can also be 
used. The font unit value is taken as the QUAD WIDTH property of the font. 
The function XmSetFontUnits allows applications to specify the font unit values. 

XmNuserData 

Allows the application to attach any necessary specific data to the widget. An inter- 
nally unused resource. 

Dynamic Color Defaults 

The foreground, background, top shadow, and bottom shadow resources are dynamically 
defaulted. If no color data is specified, the colors are automatically generated. On a mono- 
chrome system, a black and white color scheme is generated. On a color system, a set of 
four colors are generated which display the correct shading for the 3-D visuals. 

If the background is the only color specified for a widget, the top shadow, bottom shadow, 
and foreground colors are generated to give the 3-D appearance. The color generation 
works best with non-saturated colors. Using pure red, green, or blue yields poor results. 

Colors are generated at creation only. Resetting the background through XtSetValues will 
not regenerate the other colors. 
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Inherited Resources 

Manager inherits the following resources from the named superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 




Class 

XmCAccelerators 


Type 


Default 


Access 


XmN accelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


V T fUCDC/ '1 L.'l L.T\ DIVllAD 


CSG 








Blade 




XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPrXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCaUback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

The following set of translations are used by Manager widgets which have Gadget children. 
Since Gadgets cannot have translations associated with them, it is the responsibility of the 
Manager widget to intercept the events of interest and pass them to the appropriate Gadget 
child. 

Shift < Key >Tab: 

Moves the focus to the first item contained within the previous tab group. If the 
beginning of the tab group list is reached, it will wrap to the end of the tab group 
list. 

<Key>Tab or iCtrl<Key>Tab: 

Moves the focus to the first item contained within the next tab group. If the current 
tab group is the last entry in the tab group list, it will wrap to the beginning of the 
tab group list. 

<Key>Upor <Key>Left: 

Moves the keyboard focus to the previous Manager widget or gadget within the 
current tab group. The previous widget or gadget is the one which is the previous 
entry in the tab group's list of children. Wrapping will occur, if necessary. 

< Key > Down or < Key > Right: 

Moves the Keyboard focus to the next Manager widget or gadget within the current 
tab group. The previous widget or gadget is the one which is the next entry in the 
tab group's list of children. Wrapping will occur, if necessary. 

< Key > Home: 

Moves the keyboard focus to the first Manager widget or gadget in the current tab 
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group. 



Default Translations 



The following are translations used by all manager widgets. 
<EnterWindow>: ManagerEnterQ 



<FocusOut>: 
<FocusIn>: 



ManagerFocusOut() 
ManagerFocusIn() 



The following are the translations necesary to provide gadget event 
processing: 



< Key > space: 

< Key > Return: 
Shift < Key > Tab: 
<Key>Tab: 
Ctrl<Key>Tab: 
<Key>Up: 

< Key > Down: 

< Key > Left: 
<Key>Right: 

< Key > Home: 



ManagerGadgetSelect() 

ManagerGadget Select () 

ManagerGadgetPrevTabGroupO 

ManagerGadgetNextTabGroupO 

ManagerGadgetNextTabGroupO 

ManagerGadgetTraversePrev() 

ManagerGadgetTraverseNext() 

ManagerGadgetTraversePrev() 

ManagerGadgetTraverseNext() 

ManagerGadgetTraverseHome() 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), and XmGadget3X). 
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NAME 

XmMenuPosition - a RowColumn function that positions a Popup MenuPane. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

void XmMenuPosition (menu, event) 

Widget menu; 
XButtonPressedEvent * event; 

DESCRIPTION 

XmMenuPosition positions a Popup MenuPane using the information in the specified event. 
Unless an application is positioning the MenuPane itself, it must first invoke this function before 
managing the PopupMenu. The xjoot and yjoot values in the specified event are used to deter- 
mine the menu position. 

menu Specifies the PopupMenu which is to be positioned. 

event Specifies the event passed to the action procedure which manages the Popup- 

Menu. 

For a complete definition of RowColumn and its associated resources, see XmRow€olumn(3X). 

RELATED INFORMATION 

XmRowColumn(3X). 
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NAME 

XmMenuShell - the MenuShell widget class. 

SYNOPSIS 

#include <Xm/MenuShelLh> 

DESCRIPTION 

The MenuShell widget is a custom OverrideShell widget. An OverrideShell widget bypasses the 
window manager when displaying itself. It is designed specifically to contain Popup or Pulldown 
MenuPanes. 

Most application writers will never encounter this widget if they use the menu system convenience 
functions, XmCreatePopupMenu or XmC reat ePu 1 Id own Menu, to create a Popup or Pulldown 
MenuPane. The convenience functions automatically create a MenuShell widget as the parent of 
the MenuPane. However, if the convenience functions are not used, then it is the application 
programmer's responsibility to create the required MenuShell. In this case, it is important to note 
that the parent of the MenuShell depends on the type of menu system being built. 

• If the MenuShell is for the top-level Popup MenuPane, the MenuShell must be created as a 
child of the widget from which the Popup MenuPane is popped up. 

• If the MenuShell is for a MenuPane that is pulled down from a Popup or another Pulldown 
MenuPane, the MenuShell must be created as a child of the Popup or Pulldown MenuPane's 
parent MenuShell. 

• If the MenuShell is for a MenuPane that is pulled down from a MenuBar, then the MenuShell 
must be created as a child of the MenuBar. 

• If the MenuShell is for a Pulldown MenuPane in an OptionMenu, the MenuShell must have 
the same parent as the OptionMenu. 

Classes 

MenuShell inherits behavior and resources from Core, Composite, Shell, and OverrideShell 
classes. 

The class pointer is xmMenuShellWidgetCIass. 
The class name is XmMenuShell. 

New Resources 

MenuShell defines no new resources, but overrides the XmNallowShellResize resource in 
Shell. 

Inherited Resources 

MenuShell inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. The following 
tables define a set of widget resources used by the programmer to specify data. The pro- 
grammer can set the resource values for these inherited classes to set attributes for this 
widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN or 
XmC prefix and use the remaining letters. To specify one of the defined values for a 
resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either 
lower case or upper case, but include any underscores between words). The codes in the 
access column indicate if the given resource can be set at creation time (C), set by using 
XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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Shell Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowShellResize 


XmCAJlowShellResize 


Boolean 


True 


G 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


G 


XmNcreatePopupChildProc 


XmCCreatePopupChildProc 


XmCreatePopupChildProc 


NULL 


CSG 


XmNdepth 


XmCDepCh 


int 


ShellDepth 


CSG 


XmNgeometiy 


XmCGeometry 


caddr t 


NULL 


CSG 


XmNoverrideRedirect 


XmCOverrideRedirect 


Boolean 


True 


CSG 


XmNpopdcwnCallback 


XmCCallbadc 


caddr t 


NULL 


C 


XmNpopupCallback 


XmCCallbadc 


caddr t 


NULL 


C 


XmNsaveUnder 


XmCSaveUnder 


Boolean 


True 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPositioti 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


ShellAncestorSensitive 


CSG 


XmNbackground 


XmCBackground 


Pixel 


White 


CSG 


XmNbadcgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


ShellColormap 


CG 


XmNdepth 


XmCDepth 


int 


ShellDepth 


CG 


XmNdestroyCallback 


XmCCallbadc 


XtCallbackList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWbenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

The specific mouse button that is used depends upon the resources XmNrowColumnType 
and XmNwhichButton in the menu's top level RowColumn widget. 

Default PopupMenu System 
<Btn3Down>: 

If this event has not already been processed by another menu component, then this 
action disables keyboard traversal for the menus and returns the user to drag mode. 

<Btn3Up>: 

If this event has not already been processed by another menu component, then all 
visible MenuPanes are unposted. 

< Key > Escape: 

If this event has not already been processed by another menu component, then all 
visible MenuPanes are unposted. 
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Default PulldownMenu System or OptionMenu System 
<BtnlDown>: 

If this event has not already been processed by another menu component, then this 
action disables keyboard traversal for the menus and returns the user to drag mode. 

<BtnlUp>: 

If this event has not already been processed by another menu component, then all 
visible MenuPanes are unposted. 

< Key > Escape: 

If this event has not already been processed by another menu component, then all 
visible MenuPanes are unposted. 



Default Translations 



The default translations for MenuShell are: 

<BtnDown>: ClearTraversal() 

< Key > Escape: MenuShellPopdownDone() 

<BtnUp>: MenuShellPopdownDoneO 



RELATED INFORMATION 

Composite(3X), Core(3X), OverrideShell(3X), Shell(3X), XmCreateMenuShell(3X), 
XmCreatePopupMenu(3X), XmCreatePulldown(3X), and XmRowColumn(3X). 
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NAME 

XmMessageBox - the MessageBox widget class. 

SYNOPSIS 

#include < Xm /MessageB.h > 

DESCRIPTION 

MessageBox is a dialog class used for creating simple message dialogs. Convenience dialogs 
based on MessageBox are provided for several common interaction tasks, which include giving 
information, asking questions, and reporting errors. 

A MessageBox dialog is typically transient in nature, displayed for the duration of a single interac- 
tion. MessageBox is a subclass of XmBulletinBoard and depends on it for much of its general dia- 
log behavior. 

A MessageBox can contain a message symbol, a message, and up to three standard default Push- 
Buttons: OK, Cancel, and Help. It is laid out with the symbol in the top left, the message in the 
top and center-to-right side, and the PushButtons on the bottom. The help button is positioned to 
the far right of the other PushButtons. Default symbols and button labels for MessageBox con- 
venience dialogs are localizable. 

Button label defaults are easily modified by including the new values in any of the app-defaults file 
locations supported by Xt Intrinsics. Changing the defaults for MessageBox symbols is more com- 
plicated, since the Xt Intrinsics do not support specification of pixmaps by name in resource files. 

At initialization, MessageBox looks for the following bitmap files: 

• xmerror 

• xm_information 

• xm_question 

• xmworking 

• xm_warning 

See XmGetPixmap(3X) for a description of what paths are searched for these files. 
Classes 

MessageBox inherits behavior and resources from Core, Composite, Constraint, 
XmManager, and XmBulletinBoard. 

The class pointer is xmMessageBoxWidgetCIass. 

The class name is XmMessageBox. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between- words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmMessageBox Resource Set 


Name 


Class 


Tm 


Default 


Access 


XmNcancelCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNcancelLabelString 


XmCXmString 


XmString 


"Cancel" 


CSG 


XmNdefaultButtonType 


XmCDefaultButtoriiype 


unsigned char 


XmDIALOG OK BUTTON 


CSG 


XmNdialogType 


XmCDialogType 


unsigned char 


XmDIALOGMESSAGE 


CSG 


XmNhelpLabelString 


XmCXmString 


XmString 


"Help" 


CSG 


XmNmessageAlignment 


XmCAlignment 


unsigned char 


XmALIGNMENTBEGINNING 


CSG 


XmNmessageString 


XmCXmString 


XmString 


NULL 


CSG 


XmNminimizeButtons 


XmCMinimizeButtons 


Boolean 


False 


CSG 


XmNokCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNokLabelString 


XmCXmString 


XmString 


"OK" 


CSG 


XmNsymbolPixmap 


XmCPixmap 


Pixmap 


dynamic 


CSG 



XmNcancelCallback 

Specifies the list of callbacks that is called when the user clicks on the cancel button. 
The reason sent by the callback is XmCR CANCEL. 

XmNcancelLabelString 

Specifies the string label for the cancel button. 

XmNdefaultButtonType 

Specifies the default PushButton. The following are valid types: 

• XmDIALOGCANCELBUTTON. 

• XmDIALOG OK BUTTON. 

• XmDIALOG HELP BUTTON. 
XmNdialogType 

Specifies the type of MessageBox dialog, which determines the default message 
symbol. The following are the possible values for this resource: 

• XmDIALOG ERROR - indicates an ErrorDialog. 

• XmDIALOG INFORMATION - indicates an InformationDialog. 

• XmDIALOG MESSAGE - indicates a MessageDialog. This is the default Mes- 
sageBox dialog type. The default message symbol is NULL. 

• XmDIALOG QUESTION - indicates a QuestionDialog. 

• XmDIALOG WARNING - indicates a WarningDialog. 

• XmDIALOG WORKING - indicates a WorkingDialog. 

If this resource is changed via XtSetValues, the symbol bitmap will be modified to 
the new XmdialogType bitmap unless XmNsymbolPixmap is also being set in XtSet- 
Values. 

XmNhelpLabelString 

Specifies the string label for the help button. 

XmNmessageAlignment 

Controls the alignment of the message Label. Possible values include the following: 

• XmALIGNMENT BEGINNING - the default. 

• XmALIGNMENTCENTER. 

• XmALIGNMENT END. 

XmNmessageString 

Specifies the string to be used as the message. 

XmNminimizeButtons 

Sets the buttons to the width of the widest button and height of the tallest button if 
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False. If True, button width and height are set to the preferred size of each button. 
XmNokCallback 

Specifies the list of callbacks that is called when the user clicks on the OK Button. 
The reason sent by the callback is XmCR_OK. 

XmNokLabelString 

Specifies the string label for the OK button. 

XmNsymbolPixmap 

Specifies the pixmap label to be used as the message symbol. 

Inherited Resources 

MessageBox inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmBulletin Board Resource Set 


Name 


Class 


lype 


Default 




XmNallowOverlap 


XmCAllowOverlap 


Boolean 


True 


N/A 


XmNautoUnmanage 


XmCAutoUnmanage 


Boolean 


True 


CSG 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


CSG 


XmNcancelButton 


XmCWidget 


Widget 


Cancel button 


G 


XmNdefaultButton 


XmCWidget 


Widget 


OK button 


G 


XmNdefaultPosition 


XmCDefeultPosition 


Boolean 


True 


CSG 


XmNdialogStyle 


XmCDialogStyle 


unsigned char 


dynamic 


CSG 


XmNdialogTitle 


XinCXmString 


XmString 


NULL 


CSG 


XmNfocusCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNlabelFontList 


XmCLabelFontList 


XmFontList 


NULL 


CSG 


XmNmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


10 


CSG 


XmNnoResize 


XmCNoResize 


Boolean 


False 


CSG 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZEANY 


CSG 


XmNshadoWIype 


XmCShadcwflype 


unsigned char 


XmSHADOWOUT 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 


XmNtextFontList 


XmCTextFontList 


XmFontList 


NULL 


N/A 


XmNtextTranslations 


XmCTranslations 


XtTranslations 


NULL 


N/A 


XmN unmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN highlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadoWThickness 


XmCShadoWThickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr_t 


NULL 


CSG 



Hewlett-Packard Company 



-3- 



Jul 27, 1989 



XmMessageBox(3X) 



XmMessageBox(3X) 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 




Default 


Access 


XmNaccelerators 


XmCAccelcnitors 


XfTranslations 


NULL 




XmNancestoi'Sensitive 


XmCSensitive 


Boolean 




Q 











CSG 


XmNto^youndPixmap 




nxmap 


XmUNSPEOFIED PIXMAP 


CSG 


XmNbordcrColor 


XmCBorderColor 




Black 


CSG 


XroNbordci*Pixm&p 


XmCPixmap 


p|^ p 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event, 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

Behavior 

Following is a summary of the behavior of MessageBox. 

< Ok Button Activated > : 

When the ok PushButton is activated, the callbacks for XmNokCallback are called. 

< Cancel Button Activated > : 

When the cancel PushButton is activated, the callbacks for XmNcancelCallback are 
called. 

< Help Button Activated > or <Key>Fl: 

When the help button or Function key 1 is pressed, the callbacks for XmNhelpCall- 
back are called. 

< Default Button Activated > : 

When the default button is pressed, the activate callbacks of the default PushButton 
are called. 
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<FocusIn>: 

When a Focusln event is generated on the widget window, the callbacks for 
XmNfocusCallback are called. 

<MapWindow>: 

When a MapWindow event is generated on the widget window, the callbacks for 
XmNmapCallback are called. 

< UnmapWindow > : 

When a UnmapWindow event is generated on the widget window, the callbacks for 
XmNunmapCallback are called. 

Default Accelerators 

The default accelerator translations added to descendants of a BulletinBoard if the parent of 
the BulletinBoard is a DialogShell are: 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateErrorDialog(3X), 
XmCreateInformationDialog(3X), XmCreateMessageBox(3X), XmCreateMessageDialog(3X), 
XmCreateQuestionDialog(3X), XmCreateWarningDialog(3X), XmCreateWorkingDialog(3X), 
XmManager(3X), and XmMessageBoxGetChild(3X). 
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<Key>Fl: 
<Key>Return: 
<Key>KP Enten 



Help() 

Return() 

ReturnQ 
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NAME 

XmMessageBoxGetChild - a MessageBox function that is used to access a component. 

SYNOPSIS 

#include < Xm/MessageB.h > 

Widget XmMessageBoxGetChild (widget, child) 
Widget widget} 
unsigned char child} 

DESCRIPTION 

XmMessageBoxGetChild is used to access a component within a MessageBox. the parameters 
given to the function are the MessageBox widget and a value indicating which child to access. 

widget Specifies the MessageBox widget ID. 

child Specifies a component within the MessageBox. The following are legal values for 

this parameter 

• XmDIALOG CANCFX BUTTON. 

• XmDIALOGDEFAULTBUITON. 

• XmDIALOGHELPBUTTON. 

• XmDIALOG MESSAGE LABEL. 

• XmDIALOGOKBUTTON. 

• XmDIALOGSEPARATOR. 

• XmDIALOGSYMBOLLABEL. 

For a complete definition of MessageBox and its associated resources, see XmMessageBox(3X). 

RETURN VALUE 

Returns the widget ID of the specified MessageBox child. 

RELATED INFORMATION 

XmMessageBox(3X). 
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NAME 

XmOptionButtonGadget - a RowColumn function that obtains the widget ID for the Cascade- 
ButtonGadget in an OptionMenu. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmOptionButtonGadget (option jnenu) 
Widget option jnenu; 

DESCRIPTION 

XmOptionButtonGadget provides the application with the means for obtaining the widget ID for 
the internally created CascadeButtonGadget Once the application has obtained the widget ID, it 
has the ability to adjust the visuals for the CascadeButtonGadget, if desired. 

When an application creates an instance of the OptionMenu widget, the widget creates two inter- 
nal gadgets. One is a LabelGadget that is used to display RowColumn's XmNlabelString 
resource. The other is a CascadeButtonGadget that displays the current selection and provides 
the means for posting the OptionMenu's submenu. 

option jnenu Specifies the OptionMenu widget ID. 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the widget ID for the internal button. 

RELATED INFORMATION 

XmCreateOptionMenu(3X), XmCascadeButtonGadget(3X), XmOptionLabelGadget(3X), and 
XmRowColumn(3X). 
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NAME 

XmOptionLabelGadget - a RowColumn function that obtains the widget ID for the LabelGadget 
in an OptionMenu. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

Widget XmOptionLabelGadget (option jnenu) 
Widget option jnenu; 

DESCRIPTION 

XmOptionLabelGadget provides the application with the means for obtaining the widget ID for 
the internally created LabelGadget. Once the application has obtained the widget ID, it has the 
ability to adjust the visuals for the LabelGadget, if desired. 

When an application creates an instance of the OptionMenu widget, the widget creates two inter- 
nal gadgets. One is a LabelGadget that is used to display RowColumn's XmNlabelString 
resource. The other is a CascadeButtonGadget that displays the current selection and provides 
the means for posting the OptionMenu's submenu. 

option jnenu Specifies the OptionMenu widget ID. 

For a complete definition of RowColumn and its associated resources, see XmRowColumn(3X). 

RETURN VALUE 

Returns the widget ID for the internal label. 

RELATED INFORMATION 

XmCreateOptionMemi(3X), XmLabelGadget(3X), XmOptionButtonGadget(3X), and 
XmRowColumn(3X). 
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NAME 

XmPaned Window - the PanedWindow widget class. 

SYNOPSIS 

#include <Xm/PanedW.h> 

DESCRIPTION 

PanedWindow is a composite widget that lays out children in a vertically tiled format. Children 
appear in top-to-bottom fashion, with the first child inserted appearing at the top of the 
PanedWindow and the last child inserted appearing at the bottom. The PanedWindow will grow 
to match the width of its widest child and all other children are forced to this width. The height of 
the PanedWindow will be equal to the sum of the heights of all its children, the spacing between 
them, and the size of the top and bottom margins. 

It is also possible for the end user to adjust the size of the panes. To facilitate this adjustment, a 
pane control sash is created for most children. The sash appears as a square box positioned on 
the bottom of the pane that it controls. The user can adjust the size of a pane by using the mouse. 

The PanedWindow is also a constraint widget, which means that it creates and manages a set of 
constraints for each child. It is possible to specify a minimum and maximum size for each pane. 
The PanedWindow will not allow a pane to be resized below its minimum size nor beyond its max- 
imum size. Also, when the minimum size of a pane is equal to its maximum size, then no control 
sash will be presented for that pane or for the lowest pane. 

Classes 

PanedWindow inherits behavior and resources from the Core, Composite, Constraint, and 
XmManager classes. 

The class pointer is xmPanedWindowWidgetClass. 
The class name is XmPaned Window. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



Xm PanedWindow Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNmarginHeight 


XmCMarginHeight 


short 


3 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


3 


CSG 


XmNrefigureMode 


XmCBoolean 


Boolean 


True 


CSG 


XmNsashHeight 


XmCSashHeignt 


Dimension 


10 


CSG 


XmNsashlndent 


XrnCSashlndent 


Position 


-10 


CSG 


XmNsasbShadovtThickness 


XmCShadowThickness 


int 


2 


CSG 


XmNsashWidth 


XmCSashWklth 


Dimension 


10 


CSG 


XmNseparatorOn 


XmCScparatorOn 


Boolean 


True 


CSG 


XmNspacing 


XmCSpacing 


int 


8 


CSG 



XmNmarginHeight 

Specifies the distance between the top and bottom edges of the PanedWindow and 
its children. 
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XmNmarginWidth 

Specifies the distance between the left and right edges of the PanedWindow and its 
children. 

XmNrefigureMode 

Determines whether the panes' positions will be recomputed and repositioned when 
programmatic changes are being made to the PanedWindow. Setting this resource 
to True will reset the children to their appropriate positions. 

XmNsashHeight 

Specifies the height of the sash. 

XmNsashlndent 

Specifies the horizontal placement of the sash along each pane. A positive value 
will cause the sash to be offset from the left side of the PanedWindow, and a nega- 
tive value will cause the sash to be offset from the right side of the PanedWindow. 
If the offset is greater than the width of the PanedWindow minus the width of the 
sash, the sash will be placed flush against the left-hand side of the PanedWindow. 

XmNsashShadowThickness 

Specifies the thickness of the shadows of the sashes. 

XmNsashWidth 

Specifies the width of the sash. 

XmNseparatorOn 

Determines whether a separator will be created between each of the panes. Setting 
this resource to True will create a Separator at the midpoint between each of the 
panes. 

XmNspacing 

Specifies the distance between each child pane. 



XmPanedWindow Constraint Resource Set 


Name 

XmNallowResize 


Class 

XmCBoolean 


Boolean 


Default 

False 


Access 
CSG 


XmNmax 


XmCMax 


int 


1000 


CSG 


XmNmin 


XmCMin 


int 


1 


CSG 


XmNskipAdjust 


XmCBoolean 


Boolean 


False 


CSG 



XmNallowResize 

Allows an application to specify whether the PanedWindow should allow a pane to 
request to be resized. This flag only has an effect after the PanedWindow and its 
children have been realized. If this flag is set to True, the PanedWindow will try to 
honor requests to alter the height of the pane. If False, it will always deny pane 
requests to resize. 

XmNmaximum 

Allows an application to specify the maximum size to which a pane may be resized. 
This value must be greater than the specified minimum. 

XmNminimum 

Allows an application to specify the minimum size to which a pane may be resized. 
This value must be greater than 0. 

XmNskipAdjust 

When set to True, this Boolean resource allows an application to specify that the 
PanedWindow should not automatically resize this pane. 

Inherited Resources 

PanedWindow inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 
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XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbcittomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmN foreground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadoWrhickness 


XmCShadctaflThickness 


short 


0 


N/A 


XmN topShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrj 


NULL 


CSG 



Composite Resource Set 


Name 

XmNinsertPosition 


Class 


Type 


Default 

NULL 


Access 

CSG 


XmCInsertPosition 


XmRFunction 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTra relations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED_PDCMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED_PDCMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepCh 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

Shift < BtnlDown >: 

(in sash): Activates the interactive placement of the pane's borders. It changes the 
pointer cursor from a crosshair to an upward pointing arrow to indicate that the 
upper pane will be adjusted (usually the pane to which the sash is attached). All 
panes below the sash that can be adjusted, will be adjusted. 

<BtnlDown>: 

(in sash): Activates the interactive placement of the pane's borders. It changes the 
pointer cursor from a crosshair to a double headed arrow to indicate that the pane 
to be adjusted is the pane to which the sash is attached and the first pane below it 
the can be adjusted. Unlike pane adjustment using Shift BtnlDown or CTRL 
BtnlDown, only two panes will be affected. If one of the panes reaches its minimum 
or maximum size, adjustment will stop, instead of finding the next adjustable pane. 
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CTRL <BtnlDown>: 

(in sash): Activates the interactive placement of the pane's borders. It changes the 
pointer cursor from a crosshair to a downward pointing arrow to indicate that the 
lower pane will be adjusted (usually the pane below the pane to which the sash is 
attached). All panes above the sash that can be adjusted, will be adjusted. 

Shift Buttonl < PtrMoved > : 

If the button press occurs within the sash, the motion events draw a series of track 
lines to illustrate what the heights of the panes would be if the Commit action were 
invoked. This action determines which pane below the upper pane can be adjusted 
and makes the appropriate adjustments. 

Buttonl < PtrMoved > : 

If the button press occurs within the sash, the motion events draw a series of track 
lines to illustrate what the heights of the panes would be if the Commit action were 
invoked. This action adjusts as needed (and possible) the upper and lower panes 
selected when the BtnlDown action was invoked. 

CTRL Buttonl < PtrMoved > : 

If the button press occurs within the sash, the motion events draw a series of track 
lines to illustrate what the heights of the panes would be if the Commit action were 
invoked. This action determines which pane above the lower pane can be adjusted 
and makes the appropriate adjustments. 

Any<BtnUp>: 

Commits to any action taken since the interactive placement was activated. The 
sashes and the pane boundaries are moved to the committed positions of the panes. 

Default Translations ^ 

The following are default translations for Paned Window: 



Shift < BtnlDown >: 
<BtnlDown>: 
CTRL < BtnlDown >: 
Shift <BtnlMotion>: 
<BtnlMotion>: 
CTRL < BtnlMotion > : 
Any<BtnUp>: 

< EnterWindow > : 

< LeaveWindow > : 



SashAction(Start, UpperPane) 
SashAction(Start, ThisBorderOnly) 
SashAction(Start, LowerPane) 
SashAction(Move, Upper) 
SashAction(Move, ThisBorder) 
SashAction(Move, Lower) 
SashAction(Commit) 
enter() 
leaveQ 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreatePanedWindow(3X), and XmManager(3X). 
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NAME 

XmPrimitive - the Primitive widget class. 

SYNOPSIS 

#include <Xm/Xm.h> 

DESCRIPTION 

Primitive is a widget class used as a supporting superclass for other widget classes. It handles 
border drawing and highlighting, traversal activation and deactivation, and various callback lists 
needed by Primitive widgets. 

Classes 

Primitive inherits behavior and resources from Core class. 
The class pointer is xmPrimitiveWidgetClass. 
The class name is XmPrimitive. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetVahies (G), or is not applicable (N/A). 



XmPrimitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadcwPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCaUbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN highlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThickness 


XmCHighlightThickness 


short 


0 


CSG 


XroNshadoWThickness 


XmCShadoWThickness 


short 


2 


CSG 


XmN topShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



XmNbottomShadowColor 

Specifies the pixmap to use to draw the top and left sides of the border shadow. 

XmNbottomShadowPixmap 

Specifies the pixmap to use to draw the bottom and right sides of the border sha- 
dow. 

XmNforeground 

Specifies the foreground drawing color used by Primitive widgets. 

XmNhelpCallback 

Specifies the list of callbacks that is called when the help key sequence is pressed. 
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The reason sent by the callback is XmCR_HELP. There is not a translation bound 
to this resource. It is up to the application to install a translation for help. 

XmNhighlightCoIor 

Specifies the color of the highlighting rectangle. This color is used if the highlight 
pixmap resource is XmUNSPECIFIED PIXMAP. 

XmNhighlightOnEnter 

Specifies if the highlighting rectangle is drawn when the cursor moves into the 
widget. If this resource is True and XmNtraversalOn is False, then the rectangle 
highlights the window when the cursor is moved into it. This resource is ignored if 
the XmNtraversalOn resource is set to True. 

XmNhighlightPixmap 

Specifies the pixmap used to draw the highlighting rectangle. 

XmNhighlightThickness 

Specifies the thickness of the highlighting rectangle. 

XmNshadowThickness 

Specifies the size of the drawn border shadow. 

XmNtopShadowColor 

Specifies the pixmap to use to draw the top and left sides of the border shadow. 
This color is used if the XmNtopShadowPixmap resource is NULL. 

XmNtopShadowPixmap 

Specifies the pixmap to use to draw the top and left sides of the border shadow. 

XmNtraversalOn 

Specifies if traversal is activated for this widget. 

XmNunitType 

Provides the basic support for resolution independence. It defines the type of units 
a widget will use with sizing and positioning resources. Unless the XmNunitType 
resource is explicitly set, it will default to the unit type of the parent widget If the 
parent has a unit type of XmlOOTH POINTS, then any of its children whose 
XmNunitType resource is not set will also have a unit type of XmlOOTH POINTS. 
This feature applies only to widgets whose parents are a subclass of XmManager. 
Widgets whose parents are not subclasses of XmManager will have a unit type of 
XmPIXELS. 

XmNunitType can have the following values: 

• XmPIXELS - all values provided to the widget are treated as normal pixel 
values. This is the default for the resource. 

• XmlOOTH MILLIMETERS - all values provided to the widget are treated as 
1/100 millimeter. 

• XmlOOOTHJNCHES - all values provided to the widget are treated as 1/1000 
inch. 

• Xml00TH_POINTS - all values provided to the widget are treated as 1/100 
point. A point is a unit typically used in text processing applications and is 
defined as 1/72 inch. 

• XmlOOTH FONT UNITS - all values provided to the widget are treated as 
1/100-font unit. The value to be used for the font unit is determined in one of 
two ways. The resource XmNfont can be used in a defaults file or on the com- 
mand line. The standard command line options of -m and -font can also be 
used. The font unit value is taken as the QUAD_WIDTH property of the font. 
The function XmSetFontUnits allows applications to specify the font unit values. 

XmNuserData 

Allows the application to attach any necessary specific data to the widget. It is an 
internally unused resource. 
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Dynamic Color Defaults 

The foreground, background, top shadow, and bottom shadow resources are dynamically 
defaulted. If no color data is specified, the colors are automatically generated. On a mono- 
chrome system, a black and white color scheme is generated. On a color system, a set of 
four colors are generated which display the correct shading for the 3-D visuals. 

If the background is the only color specified for a widget, the top shadow, bottom shadow, 
and foreground colors are generated to give the 3-D appearance. The color generation 
works best with non-saturated colors. Using pure red, green, or blue yields poor results. 

Colors are generated at creation only. Resetting the background through XtSetValues will 
not regenerate the other colors. 



Inherited Resources 

Primitive inherits behavior and resources from the following superclass. For a complete 
description of these resources, refer to the man page for that superclass. 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmN screen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmN sensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Behavior 

Shift < Key >Tab: 

Moves the focus to the first item contained within the previous tab group. If the 
beginning of the tab group list is reached, it will wrap to the end of the tab group 
list. 

<Key>Tab or Ctrl<Key>Tab: 

Moves the focus to the first item contained within the next tab group. If the current 
tab group is the last entry in the tab group list, it will wrap to the beginning of the 
tab group list. 

<Key>Up or < Key > Left: 

Moves the keyboard focus to the previous Primitive widget or gadget within the 
current tab group. The previous widget or gadget is the one which is the previous 
entry in the tab group's list of children. Wrapping will occur, if necessary. 

< Key > Down or < Key > Right: 

Moves the Keyboard focus to the next Primitive widget or gadget within the current 
tab group. The previous widget or gadget is the one which is the next entry in the 
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tab group's list of children. Wrapping will occur, if necessary. 
< Key > Home: 

Moves the keyboard focus to the first Primitive widget or gadget in the current tab 
group. 



Default Translations 

The following are the default translations for Primitive: 



<FocusIn>: 

<FocusOut>: 

<Unmap>: 

Shift <Key>Tab: 

<Key>Tab: 

Ctrl<Key>Tab: 

<Key>Up: 

<Key>Down: 

< Key > Left: 

< Key > Right: 

< Key > Home: 



PrimitiveFocusInO 

PrimitiveFocusOutO 

PrimitiveUnmapO 

PrimitivePrevTabGroupO 

PrimitiveNextTabGroupO 

PrimitiveNextTabGroupO 

PrimitiveTraversePrevO 

PrimitiveTraverseNext() 

PrimitiveTraversePrev() 

PrimitiveTraverseNextO 

PrimitiveTraverseHomeO 



RELATED INFORMATION 
Core(3X). 
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NAME 

XmPushButton - the PushButton widget class. 

SYNOPSIS 

# include <Xm/PushB.h> 

DESCRIPTION 

PushButton issues commands within an application. It consists of a text label or pixmap sur- 
rounded by a border shadow. When PushButton is selected, the shadow moves to give the appear- 
ance that it has been pressed in. When PushButton is unselected, the shadow moves to give the 
appearance that it is out. 

The behavior of PushButton differs, depending on the active mouse button. The active mouse but- 
ton may be determined by the parent widget. Normally, mouse button 1 is used to arm and 
activate the PushButton. However, if the PushButton resides within a menu, then the mouse but- 
ton used is determined by the RowColumn resources XmNrowColumnType and XmNwhichBut- 
ton. 

Thickness for a second shadow may be specified by using the XmNshowAsDefauIt resource. If it 
has a non-zero value, the Label's resources XmNmarginLeft, XmNmarginRight, XmNmarginTop, 
and XmNmarginBottom may be modified to accommodate the second shadow. 

Classes 

PushButton inherits behavior and resources from Core, XmPrimitive, and XmLabel classes. 
The class pointer is xmPushButtonWidgetClass. 
The class name is XmPushButton. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSet Values (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmPushButton Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNarmColor 


XmCArmColor 


Pixel 


dynamic 


CSG 


XmNarmPixmap 


XmCArmPixmap 


Pixmap 


XmUNSPECIFTEDPIXMAP 


CSG 


XmNdisarmCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNfillOnArm 


XmCFillOnArm 


Boolean 


True 


CSG 


XmNshowAsDefauIt 


XmCSbcwAsDe fault 


short 


0 


CSG 



XmNactivateCallback 

Specifies the list of callbacks that is called when PushButton is activated. PushBut- 
ton is activated when the user presses and releases the active mouse button while 
the pointer is inside that widget. Activating the PushButton also disarms it. For this 
callback the reason is XmCRACTTVATE. 

XmNarmCallback 

Specifies the list of callbacks that is called when PushButton is armed. PushButton 
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is armed when the user presses the active mouse button while the pointer is inside 
that widget For this callback the reason is XmCR_ARM. 

XmNarmColor 

Specifies the color with which to fill the armed button. XmNfillOnArm must be set 
to True for this resource to have an effect The default for a color display is a color 
between the background and the bottom shadow color. For a monochrome display, 
the default is set to the foreground color, and any text in the label will appear in the 
background color when the button is armed. 

XmNarmPixmap 

Specifies the pixmap to be used as the button face if XmNlabeltype is XmPIXMAP 
and PushButton is armed. This resource is disabled when the PushButton is in a 
menu. 

XmNdisarmCallback 

Specifies the list of callbacks that is called when PushButton is disarmed. PushBut- 
ton is disarmed when the user presses and releases the active mouse button while 
the pointer is inside that widget. For this callback, the reason is XmCR_DISARM. 

XmNfillOnArm 

Forces the PushButton to fill the background of the button with the color specified 
by XmNarmColor when the button is armed and when this resource is set to True. 
If False, only the top and bottom shadow colors are switched. When the PushButton 
is in a menu, this resource is ignored and assumed to be False. 

XmNshowAsDefault 

Specifies a shadow thickness for a second shadow to be drawn around the PushBut- 
ton to visually mark it as a default button. The space between the shadow and the 
default shadow is equal to the sum of both shadows. The default value is zero. 
When this value is not zero, the Label resources XmNmarginLeft, XmNmargin- 
Right, XmNmarginTop, and XmNmarginBottom may be modified to accommodate 
the second shadow. This resource is disabled when the PushButton is in a menu. 



Inherited Resources 

PushButton inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



Xm Label Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerator 


XmCAccelerator 


String 


NULL 


CSG 


XmNacceleratoiText 


XmCAcceleratorText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


dynamic 


CSG 


XmNmarginHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


dynamic 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


dynamic 


CSG 


XmNmarginTop 


XmCMarginTop 


short 


dynamic 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


<\0' 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 
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Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShacJowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmN foreground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThidmess 


XmCHighlightThidcness 


short 


0 


CSG 


XmNshadowThickness 


XmCShadowThidcness 


short 


2 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XroNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPDCELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 




Core Resource Set 


Name 


Class 


T>pe 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNbordcrWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadt 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event; 

} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. This event will be NULL 

for the XmNactivateCallback if the callback was triggered when Primitive's 
resource XmNtraversalOn was True or if the callback was accessed through 
the ArmAndActivate action routine. 



Hewlett-Packard Company 



-3- 



Aug 28, 1989 



XmPushButton(3X) 



Xm PushButton (3X) 



Behavior 

PushButton is associated with the default behavior unless it is part of a menu system. In a 
menu system, the RowColumn parent determines which mouse button is used. 

Default Behavior 
<BtnlDown>: 

This action causes the PushButton to be armed. The shadow is drawn in the armed 
state, and the button is filled with the color specified by XmNarmColor if 
XmNfillOnArm is set to True. The callbacks for XmNarmCallback are also called. 

<BtnlUp>: 

(in button): This action redraws the shadow in the unarmed state. The background 
color will revert to the unarmed color if XmNfillOnArm is set to True. The call- 
backs for XmNactivateCallback are called, followed by callbacks for XmNdisarm- 
Callback 

(outside of button): This action causes the callbacks for XmNdisarmCallback to be 
called. 

< Leave Window > : 

If the button is pressed and the cursor leaves the widget's window, the shadow is 
redrawn in its unarmed state, and the background color will revert to the unarmed 
color if XmNfillOnArm is set to True. 

< Enter Window >: 

If the button is pressed and the cursor leaves and reenters the widget's window, the 
shadow is drawn in the armed state, and the button is filled with the color specified 
by XmNarmColor if XmNfillOnArm is set to True. 

Default PopupMenu System 
<Btn3Down>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
The shadow is drawn in the armed state, and the callbacks for XmNarmCallback 
are called. 

<Btn3Up>: 

This action causes the PushButton to be activated and the menu to be unposted. 
The callbacks for XmNactivateCallback are called, followed by callbacks for 
XmNdisarmCallback 

< Leave Window > : 

If button 3 is pressed and the cursor leaves the widget's window, the PushButton will 
be redrawn with no shadow. The callbacks for XmNdisarmCallback are called. If 
keyboard traversal is enabled in the menu, then this event is ignored. 

< Enter Window >: 

If button 3 is pressed and the cursor enters the widget's window, the shadow will be 
drawn in the armed state. The callbacks for XmNarmCallback are called. If key- 
board traversal is enabled in the menu, then this event is ignored. 

< Key > Return: 

If keyboard traversal is enabled in the menu, then this event will cause the PushBut- 
ton to be activated and the menu to be unposted. The callbacks for XmNactivate- 
Callback are called, followed by callbacks for XmNdisarmCallback. 

Default PulldownMenu and OptionMenu System 
<BtnlDown>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
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The shadow is drawn in the armed state, and the callbacks for XmNarmCallback 
are called. 

<BtnlUp>: 

This action causes the PushButton to be activated and the menu to be unposted. 
The callbacks for XmNactivateCallback are called, followed by callbacks for 
XmNdisarmCallback. 

< Leave Window > : 

If mouse button 1 is pressed and the cursor leaves the widget's window, the Push- 
Button will be redrawn with no shadow. The callbacks for XmNdisarmCallback are 
called. If keyboard traversal is enabled in the menu, then this event is ignored. 

< Enter Window >: 

If mouse button 1 is pressed and the cursor enters the widget's window, the shadow 
will be drawn in the armed state. The callbacks for XmNarmCallback are called. If 
keyboard traversal is enabled in the menu, then this event is ignored. 

<Key>Retum: 

If keyboard traversal is enabled in the menu, then this event will cause the PushBut- 
ton to be activated and the menu to be unposted. The callbacks for XmNactivate- 
Callback are called, followed by callbacks for XmNdisarmCallback. 

Default Translations 

When not in a menu system, the following are PushButton's default translations: 

<BtnlDown>: Arm() 
<BtnlUp>: Activate() 
Disarm() 

< Key > Return: ArmAndActivate() 

< Key > space: ArmAndActivate() 
<EnterWindow>: Enter() 
<LeaveWindow>: Leave() 

When in a menu system, the following are PushButton's default translations: 

<BtnDown>: BtnDown() 

<BtnUp>: BtnUpO 

<EnterWindow>: Enter() 

< Leave Window > : Leave() 
<Key>Return: KeySelect() 

< Key > Escape: MenuSheUPopdownDone() 

Keyboard Traversal 

For information on keyboard traversal when not in a menu system, see the man page for 
XmPrimitive(3X) and its sections on behavior and default translations. When in a menu 
system, the following keyboard traversal translations are defined: 

<Unmap>: Unmap() 

<FocusOut>: FocusOut() 

<FocusIn>: FocusIn() 

< Key > space: Noop() 

< Key > Left: MenuTraverseLeft() 

< Key > Right: MenuTraverseRight() 
<Key>Up: MenuTraverseUpO 

< Key > Down: MenuTraverseDown() 

< Key > Home: NoopQ 
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RELATED INFORMATION 

Core(3X), XmCreatePushButton(3X), XmLabel(3X), XmPrimitive(3X), and XmRowColumn(3X). 
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NAME 

XmPushButtonGadget - the PushButtonGadget widget class. 

SYNOPSIS 

#include <Xm/PushBG.h> 

DESCRIPTION 

PushButtonGadget issues commands within an application. It consists of a text label or icon sur- 
rounded by a border shadow. When PushButtonGadget is selected, the shadow moves to give the 
appearance that the PushButtonGadget has been pressed in. When PushButtonGadget is 
unselected, the shadow moves to give the appearance that the PushButtonGadget is out. 

The behavior of PushButtonGadget differs, depending on the active mouse button. The active 
mouse button may be determined by the parent widget. Normally, mouse button 1 is used to arm 
and activate the PushButtonGadget. However, if the PushButtonGadget resides within a menu, 
then the mouse button used is determined by the RowColumn resources XmNrowColumnType 
and XmNwhichButton. 

Thickness for a second shadow may be specified by using the XmNshowAsDefault resource. If it 
has a non-zero value, the Label's resources XmNmarginLeft, XmNmarginRight, XmNmarginTop, 
and XmNmarginBottom may be modified to accommodate the second shadow. 

Classes 

PushButtonGadget inherits behavior and resources from Object, RectObj, XmGadget and 
XmLabelGadget classes. 

The class pointer is xmPushButtonGadgetClass. 

The class name is XmPushButtonGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmPushButtonGadget 


Name 


Class 


Type 


Default 


Access 

C 


XmNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


XmNarmCallback 


XmCCallback 


caddr_t 


NULL 


C 


XmNarmColor 


XmCArmColor 


Pixel 


dynamic 


CSG 


XmNarmPixmap 


XmCArmPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNdisarmCallback 


XmCCallback 


caddrj 


NULL 


C 


XmNfillOnArm 


XmCFillOnArm 


Boolean 


True 


CSG 


XmNshowAsDefault 


XmCShowAs Default 


short 


0 


CSG 



XmNactivateCallback 

Specifies the list of callbacks that is called when the PushButtonGadget is activated. 
It is activated when the user presses and releases the active mouse button while the 
pointer is inside the PushButtonGadget. Activating PushButtonGadget also disarms 
it. For this callback the reason is XmCR ACTIVATE. 
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XmNarmCallback 

Specifies the list of callbacks that is called when PushButtonGadget is armed. It is 
armed when the user presses the active mouse button while the pointer is inside the 
PushButtonGadget. For this callback the reason is XmCR_ARM. 

XmNarmColor 

Specifies the color with which to fill the armed button. XmNfillOnArm must be set 
to True for this resource to have an effect. The default for a color display is a color 
between the background and the bottom shadow color. For a monochrome display, 
the default is set to the foreground color, and any text in the label will appear in the 
background color when the button is armed. 

XmNarmPixmap 

Specifies the pixmap to be used as the button face if XmNlabeltype is XmPIXMAP 
and PushButtonGadget is armed. This resource is disabled when the PushBut- 
tonGadget is in a menu. 

XmNdisarmCallback 

Specifies the list of callbacks that is called when the PushButtonGadget is disarmed. 
PushButtonGadget is disarmed when the user presses and releases the active mouse 
button while the pointer is inside that gadget. For this callback, the reason is 
XmCR DISARM. 

XmNfillOnArm 

Forces the PushButtonGadget to fill the background of the button with the color 
specified by XmNarmColor when the button is armed and when this resource is set 
to True. If False, only the top and bottom shadow colors are switched. When the 
PushButtonGadget is in a menu, this resource is ignored and assumed to be False. 

XmNshowAsDefault 

Specifies a shadow thickness for a second shadow to be drawn around the PushBut- 
tonGadget to visually mark it as a default button. The space between the shadow 
and the default shadow is equal to the sum of both shadows. The default value is 
zero. When this value is not zero, the Label resources XmNmarginLeft, XmNmar- 
ginRight, XmNmarginTop, and XmNmarginbottom may be modified to accommo- 
date the second shadow. This resource is disabled when the PushButtonGadget is 
in a menu. 



Inherited Resources 

PushButtonGadget inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 
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XmLabelGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerator 


XmCAooelerator 


String 


NULL 


CSG 


XmNacceleratoiText 


XmCAcceleratorText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCXabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelTvpe 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


0 


CSG 


XmNmargiaHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


0 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


0 


CSG 


XmNmarginTop 


XmCMarginTop 


short 


0 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


<\0' 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 



XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightThickness 


XmCHighlightThidcness 


short 


0 


CSG 


XmNshadoWThickness 


XmCShadoWThickness 


short 


2 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPrXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



RectObj Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XwNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event, 

} XniAnyCallbackStruct; 
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reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. This event will be NULL 

for the XmNactivateCallback if the callback was triggered when Primitive's 
resource XmNtraversalOn was True or if the callback was accessed through 
the ArmAndActivate action routine. 

Behavior 

PushButtonGadget is associated with the default behavior unless it is part of a menu system. 
In a menu system, the RowColumn parent determines which mouse button is used. 

Default Behavior 
<BtnlDown>: 

This action causes the PushButtonGadget to be armed. The shadow is drawn in the 
armed state, and the button is filled with the color specified by XmNarmColor if 
XmNfillOnArm is set to True. The callbacks for XmNarmCallback are also called. 

<BtnlUp>: 

(in button): This action redraws the shadow in the unarmed state. The background 
color will revert to the unarmed color if XmNfillOnArm is set to True. The call- 
backs for XmNactivateCallback are called, followed by callbacks for XmNdisarm- 
Callback. 

(outside of button): This action causes the callbacks for XmNdisarmCallback to be 
called. 

< Leave Window > : 

If the button is pressed and the cursor leaves the gadget's window, the shadow is 
redrawn in its unarmed state, and the background color will revert to the unarmed 
color if XmNfillOnArm is set to True. 

< Enter Window >: 

If the button is pressed and the cursor leaves and reenters the gadget's window, the 
shadow is drawn in the armed state, and the button is filled with the color specified 
by XmNarmColor if XmNfillOnArm is set to True. 

Default PopupMenu System 
<Btn3Down>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
The shadow is drawn in the armed state, and the callbacks for XmNarmCallback 
are called. 

<Btn3Up>: 

This action causes the PushButtonGadget to be activated and the menu to be 
unposted. The callbacks for XmNactivateCallback are called, followed by callbacks 
for XmNdisarmCallback. 

< Leave Window > : 

If button 3 is pressed and the cursor leaves the widget's window, the PushBut- 
tonGadget will be redrawn with no shadow. The callbacks for XmNdisarmCallback 
are called. If keyboard traversal is enabled in the menu, then this event is ignored. 

< Enter Window >: 

If button 3 is pressed and the cursor enters the widget's window, the shadow will be 
drawn in the armed state. The callbacks for XmNarmCallback are called. If key- 
board traversal is enabled in the menu, then this event is ignored. 

<Key>Return: 

If keyboard traversal is enabled in the menu, then this event will cause the PushBut- 
tonGadget to be activated and the menu to be unposted. The callbacks for 
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XmNactivateCallback are called, followed by callbacks for XmNdisarmCallback. 

Default PulldownMenu System and OptionMenu System 
<BtnlDown>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
The shadow is drawn in the armed state, and the callbacks for XmNarmCallback 
are called. 

<BtnlUp>: 

This action causes the PushButtonGadget to be activated and the menu to be 
unposted. The callbacks for XmNactivateCallback are called, followed by callbacks 
for XmNdisarmCallback. 

< Leave Window >: 

If mouse button 1 is pressed and the cursor leaves the widget's window, the Push- 
ButtonGadget will be redrawn with no shadow. The callbacks for XmNdisarmCall- 
back are called. If keyboard traversal is enabled in the menu, then this event is 
ignored. 

< Enter Window >: 

If mouse button 1 is pressed and the cursor enters the widget's window, the shadow 
will be drawn in the armed state. The callbacks for XmNarmCallback are called. If 
keyboard traversal is enabled in the menu, then this event is ignored. 

< Key > Return: 

If keyboard traversal is enabled in the menu, then this event will cause the PushBut- 
tonGadget to be activated and the menu to be unposted. The callbacks for XmNac- 
tivateCallback are called, followed by callbacks for XmNdisarmCallback. 

Keyboard Traversal 

For information on keyboard traversal outside of menu systems, see the man page for 
XmGadget(3X) and its sections on behavior and default translations. For information on 
keyboard traversal inside of menu systems, see XmRowColumn(3X). 

RELATED INFORMATION 

Object(3X), RectObj(3X), XmCreatePushButtoitGadget(3X), XmGadget(3X), 
XmLabelGadget(3X), and XmRowColumn(3X). 
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NAME 

XmRemoveProtocolCallback - a VendorShell function that removes a callback from the internal 
list. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmRemoveProtocolCallback (shell, property, protocol, callback, closure) 

Widget shell; 

Atom property; 

Atom protocol; 

XtCallbackProc callback; 

caddr_t closure; 

void XmRemoveWMProtocolCallback (shell, protocol, callback, closure) 
Widget shell; 
Atom protocol; 
XtCallbackProc callback; 
caddr_t closure; 

DESCRIPTION 

XmRemoveProtocolCallback removes a callback from the internal list 

XmRemoveWMProtocolCallback is a convenience interface. It calls XmRemoveProtocolCallback 
with the property value set to the atom returned by interning WM_PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocol Specifies the protocol atom (or an int cast to Atom). 

callback Specifies the procedure to call when a protocol message is received. 

closure Specifies the client data to be passed to the callback when it is invoked. 

For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmRemoveWMProtocolCallback(3X). 



Hewlett-Packard Company 



-1- 



Jul 27, 1989 



XmRemoveProtocols (3X) 



XmRemoveProtocols (3X) 



NAME 

XmRemoveProtocols - a VendorShell function that removes the protocols from the protocol 
manager and deallocates the internal tables. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/ProtocoIs.h> 

void XmRemoveProtocols {shell, property, protocols, num protocols) 
Widget shell-, 
Atom property; 
Atom * protocols; 

Cardinal num protocols; 

void XmRemoveWMProtocols {shell, protocols, num ^protocols) 
Widget shell; 
Atom * protocols; 

Cardinal num protocols; 

DESCRIPTION 

XmRemoveProtocols removes the protocols from the protocol manager and deallocates the inter- 
nal tables. If any of the protocols are active, it will update the handlers and update the property if 
shell is realized. 

XmRemoveWMProtocols is a convenience interface. It calls XmRemoveProtocols with the property 
value set to the atom returned by interning WMPROTOCOLS. 



shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocols Specifies the protocol atoms (or ints cast to Atom). 

num protocols Specifies the number of elements in protocols. 



For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmRemoveWMProtocols(3X). 



Hewlett-Packard Company 



-1- 



Jul 27, 1989 



XmRemoveTabGroup (3X) 



XmRemoveTabGroup (3X) 



NAME 

XmRemoveTabGroup - a function that removes a tab group. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmRemoveTabGroup (tab _group) 

Widget tab jpvup; 

DESCRIPTION 

XmRemoveTabGroup removes a Manager or Primitive widget from the list of tab groups associ- 
ated with a particular widget hierarchy. 

tab _gfoup Specifies the Manager or Primitive widget ID. 

RELATED INFORMATION 

XmAddTabGroup(3X), XmManager(3X), and XmPrimitive(3X). 
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NAME 

XmRemoveWMProtocolCallback - a VendorShell convenience interface that removes a callback 
from the internal list. 

SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmRemoveWMProtocolCallback (shell, protocol, callback, closure) 
Widget shell; 
Atom protocol; 
XtCallbackProc callback-, 
caddr_t closure; 

DESCRIPTION 

XmRemoveWMProtocolCallback is a convenience interface. It calls XmRemoveProtocolCallback 
with the properly value set to the atom returned by interning WM_PROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocol Specifies the protocol atom (or an int cast to Atom). 

callback Specifies the procedure to call when a protocol message is received. 

closure Specifies the client data to be passed to the callback when it is invoked. 

For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmRemoveProtocolCallback(3X). 
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NAME 

XmRemoveWMProtocols - a VendorShell convenience interface that removes the protocols from 
the protocol manager and deallocates the internal tables. 

SYNOPSIS 

#include <Xm/Xn*.h> 
#include <Xll/Protocols.h> 

void XmRemoveWMProtocols (shell, protocols, num protocols) 
Widget shell; 
Atom * protocols^ 

Cardinal num protocols; 

DESCRIPTION 

XmRemoveWMProtocols is a convenience interface. It calls XmRemoveProtocols with the property 
value set to the atom returned by interning WMPROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocols Specifies the protocol atoms (or ints cast to Atom). 

Hum protocols Specifies the number of elements in protocols. 

For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 

RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmRemoveProtocols(3X). 
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NAME 

XmResolvePartOffsets - a function that allows writing of upward-compatible applications and 
widgets. 

SYNOPSIS 

#include <Xm/XmP.h> 

void XmResolvePartOffsets (widget_class, offset) 
WidgetClass widget _class; 
XmOffsetPtr * offset, 



DESCRIPTION 

The use of offset records requires one extra global variable per widget class. The variable consists 
of a pointer to an array of offsets into the widget record for each part of the widget structure. The 
XmResolvePartOffsets function allocates the offset records needed by an application to guarantee 
upward-compatible applications and widgets. These offset records are used by the widget to 
access all of the widget's variables. A widget needs to take the following steps: 

• Instead of creating a resource list, the widget creates an offset resource list. To help you 
accomplish this, use the XmPartResource structure and the XmPartOffset macro. The XmPar- 
tResource data structure looks just like a resource list, but instead of having one integer for its 
offset, it has two shorts. This gets put into the class record as if it were a normal resource list. 
Instead of using XtOffset for the offset, it uses XmPartOffset. 

• Instead of putting the widget size in the class record, the widget puts the widget part in the 
same field. 

• Instead of putting XtVersion in the class record, the widget puts XtVersionDontCheck in the 
class record. 

• The widget defines a variable to point to the offset record. This can be part of the widget's 
class record or a separate global variable. 

• In class initialization, the widget calls XmResolvePartOffsets, passing it the offset address and 
the class record. This does several things: 

Adds the superclass (which, by definition, has already been initialized) size field to the part 
size field. 

Allocates an array based upon the number of superclasses. 

Fills in the offsets of all the widget parts with the appropriate values, determined by examining 
the size fields of all superclass records. 

Uses the part offset array to modify the offset entries in the resource list to be real offsets, in 
place. 

• Instead of accessing fields directly, the widget must always go through the offset table. You 
will probably define macros for each field to make this easier. Assume an integer field "xyz": 

#define BarXyz(w) (*(int *)(((char *) w) + offsetfBarlndex] + \ XtOffset(BarPart^yz))) 

The XmField macro helps you access these fields. Because the XmPartOffset and XmField 
macros concatenate things together, you must ensure there is no space before or after the part 
argument For example, the following do not work because of the space before or after the 
part (Label) argument: 

XmField(w, offset, Label, text, char *) 
XmPartOffset( Label, text). 
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Therefore, you must not have any spaces before or after the part (Label) argument, as illus- 
trated here: 



XmField(w, offset,Label, text, char *) 



The parameters for XmResoIvePartOffsets are defined below: 

widget_class Specifies the widget class pointer for the created widget 

offset Specifies the offset record. 
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NAME 

XmRowColumn - the RowColumn widget class. 

SYNOPSIS 

#include <Xm/RowColumn.h> 

DESCRIPTION 

The RowColumn widget is a general-purpose RowColumn manager capable of containing any 
widget type as a child. In general, it requires no special knowledge about how its children function 
and provides nothing beyond support for several different layout styles. However, it can be 
configured as a menu, in which case, it expects only certain children, and it configures to a particu- 
lar layout. The menus supported are: MenuBar, Pulldown or Popup MenuPanes, and Option- 
Menu. 

The type of layout performed is controlled by how the application has set the various layout 
resources. It can be configured to lay out its children in either rows or columns. In addition, the 
application can specify whether the children should be packed tightly together (not into organized 
rows and columns), or whether each child should be placed in an identically-sized box (producing 
a symmetrical look), or whether specific layout should be done (the current x and y positions of 
the children control their location). 

In addition, the application has control over both the spacing that occurs between each row and 
column and the margin spacing present between the edges of the RowColumn widget and any 
children that are placed against it. 

In most cases, the RowColumn widget has no 3-D visuals associated with it; if an application 
wishes to have a 3-D shadow placed around this widget, it can create the RowColumn as a child of 
a Frame widget. 

Classes 

RowColumn inherits behavior and resources from Core, Composite, Constraint, and 
XmManager classes. 

The class pointer is xniRowColumnWidgetClass. 
The class name is XmRowColumn. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmRowColumn Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNadjustLast 


XmCAdjustLast 


Boolean 


True 


CSG 


XmNadjustMargin 


XmCAdjustMargin 


Boolean 


True 


CSG 


XmNentryAlignment 


XmCAlignment 


unsigned char 


dynamic 


CSG 


XmNentiyBorder 


XmCEntryBorder 


short 


dynamic 


CSG 


XmNentryCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNentryOass 


XmCEntryClass 


WidgetClass 


dynamic 


CSG 


XmNisAligned 


XmCIsAligned 


Boolean 


True 


CSG 


XmN isHomogeneous 


XmCIsHomogeneous 


Boolean 


dynamic 


CSG 


XmNlabelString 


XmCString 


XmString 


NULL 


C 


XmNmapCaUback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


Dimension 


dynamic 


CSG 


XmNmargmWidth 


XmCMarginWidth 


Dimension 


3 


CSG 


XmNmenuAecelerator 


XmCAccelerators 


String 


dynamic 


CSG 


XmNmenuHelpWidget 


XmCMenuWidget 


Widget 


NULL 


CSG 


XmNmenuHistory 


XmCMenuWidget 


Widget 


NULL 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


dynamic 


CSG 


XmNnumColumns 


XmCNumColumns 


short 


dynamic 


CSG 


XmNorientation 


XmCOrientation 


unsigned char 


dynamic 


CSG 


XmNpacking 


XmCPacking 


unsigned char 


dynamic 


CSG 


XmNpopupEnabled 


XmCPopupEnabled 


Boolean 


True 


CSG 


XmNradioAlwaysOne 


XmCRadioAlwaysOne 


Boolean 


True 


CSG 


XmNradioBehavior 


XmCRadioBehavior 


Boolean 


False 


CSG 


XmNresizeHeight 


XmCResizeHeight 


Boolean 


True 


CSG 


XmNresizeWidth 


XmCResizeWidth 


Boolean 


True 


CSG 


XmNrowColumnType 


XmCRcwColumnType 


unsigned char 


XmWORKAREA 


CG 


XmNshadoWThickness 


XmCShadoWThickness 


int 


dynamic 


CSG 


XmN spacing 


XmCSpacing 


short 


dynamic 


CSG 


XmNsubMenuId 


XmCMenuWidget 


Widget 


NULL 


CG 


XmNunmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNwhichButton 


XmCWhichButton 


unsigned int 


dynamic 


CSG 



XmNadjustLast 

Extends the last row of children to the bottom edge of RowColumn (when 
XmOrientation is XmHORIZONTAL) or extends the last column to the right edge 
of RowColumn (when XmOrientation is XmVERTICAL). This feature is disabled 
by setting XmNadjustLast to False. 

XmNadjustMargin 

Specifies whether the inner minor margins of all items contained within the 
RowColumn widget are forced to the same value. The inner minor margin 
corresponds to the XmNmarginLeft, XmNmarginRight, XmNmarginTop and 
XmNmarginBottom resources supported byXmLabel and XmLabelGadget. 

A horizontal orientation causes XmNmarginTop and XmNmarginBottom for all 
items in a particular row to be forced to the same value; the value is the largest mar- 
gin specified for one of the Label items. 

A vertical orientation causes XmNmarginLeft and XmNmarginRight for all items in 
a particular column to be forced to the same value; the value is the largest margin 
specified for one of the Label items. 

This keeps all text within each row or column lined up with all other text in its row 
or column. If the XmNrowColumnType is either XmMENUPOPUP or 
XmMENU_PULLDOWN and this resource is True, only button children have their 
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margins adjusted. 
XmNentryAlignment 

Specifies the alignment type for Label or LabelGadget children when 
XmNisAligned is enabled. The following are textual alignment types: 

• XmALIGNMENTBEGINNING - the default. 

• XmALIGNMENT CENTER. 

• XmALIGNMENT END. 

See the description of XmNalignment in the XmLabel(3X) man page for an expla- 
nation of these actions. 

XmNentryBorder 

Imposes a uniform border width upon all RowColumn's children. The default value 
is 0, which disables the feature. 

XmNentryCallback 

Disables the activation callbacks for all ToggleButton, PushButton, and CascadeBut- 
ton widgets and gadgets contained within the RowColumn widget. If the application 
supplies this resource, the activation callbacks are then revectored to this callback. 
This allows an application to supply a single callback routine for handling all items 
contained in a RowColumn widget. The application must supply this resource when 
this widget is created. 

If the application does not supply this resource, then the activation callbacks for 
each item in the RowColumn widget work as normal. The callback reason is 
XmCR ACTIVATE and the default value is NULL. Changing this resource using 
the XtSetValues is not supported. 

XmNentryClass 

Specifies the only widget class that can be added to the RowColumn widget; this 
resource is meaningful only when the XmNisHomogeneous resource is set to True. 
When XmNrowColumnType is set to XmWORKAREA and XmNradioBehavior is 
True, then the default value for XmNentryClass is xmToggleButtonGadgetClass. 
When XmNrowColumnType is set to XmMENU_BAR, then the value of XmNen- 
tryClass is forced to xmCascadeButtonWidgetClass. 

XmNisAligned 

Specifies text alignment for each item within the RowColumn widget; this only 
applies to items which are a subclass of XmLabel or XmLabelGadget. However, if 
the item is a Label widget or gadget and its parent is either a Popup MenuPane or a 
Pulldown MenuPane, then alignment is not be performed; the Label is treated as 
the title within the MenuPane, and the alignment set by the application is not over- 
ridden. XmNentryAlignment controls the type of textual alignment. 

XmNisHomogeneous 

Indicates if the RowColumn widget should enforce exact homogeneity among the 
items it contains; if True, then only the widgets which are of the class indicated by 
XmNentryClass are allowed as children of the RowColumn widget. This is most 
often used when creating a MenuBar or a RadioBox widget. 

Attempting to insert a child which is not a member of the specified class generates a 
warning message. The default value is False, except when creating a MenuBar or a 
RadioBox, when the default is True. 

XmNlabelString 

Points to a text string which displays the label to the left of the selection area when 
XmNrowColumnType is set to XmMENU_OPTION. This resource is not meaning- 
ful for all other RowColumn types. If the application wishes to change the label 
after creation, it must get the LabelGadget ID (XmOptionLabelGadget) and call 
XtSetValues on the LabelGadget directly. The default value is no label. 
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XmNmapCallback 

Specifies a widget-specific callback function that is invoked when the window associ- 
ated with the RowColumn widget is about to be mapped. The callback reason is 
XmCRMap. 

XmNmarginHeight 

Specifies the amount of blank space between the top edge of the RowColumn 
widget and the first item in each column, and the bottom edge of the RowColumn 
widget and the last item in each column. The default value is three pixels. 

XmNmarginWidth 

Specifies the amount of blank space between the left edge of the RowColumn 
widget and the first item in each row, and the right edge of the RowColumn widget 
and the last item in each row. The default value is three pixels. 

XmNmenuAccelerator 

This resource is only useful when the RowColumn widget has been configured to 
operate as a Popup MenuPane or a MenuBar. The format of this resource is simi- 
lar to the left side specification of a translation string, with the limitation that it must 
specify a key event. For a Popup MenuPane, when the accelerator is typed by the 
user, the Popup MenuPane is posted. For a MenuBar, when the accelerator is 
typed by the user, the first item in the MenuBar is highlighted, and traversal is 
enabled in the MenuBar. The default for a Popup MenuPane is <Key>F4. The 
default for a MenuBar is <Key>F10. The accelerator can be disabled by setting the 
XmNpopupEnabled resource to False. 

XmNmenuHelpWidget 

Specifies the widget ID for the CascadeButton which is treated as the Help widget if 
XmNrowColumnType is set to XmMENU BAR. The MenuBar always places the 
Help widget at the lower right corner, if the RowColumn widget is of any type 
other than XmMENU_BAR then this resource is not meaningful. 

XmNmenuHistory 

Specifies the widget ID of the last menu entry to be activated. It is also useful for 
specifying the current selection for an OptionMenu. If XmNrowColumnType is set 
to XmMENU_OPTION, then the specified menu item is positioned under the cur- 
sor when the menu is displayed. 

If the RowColumn widget has the XmNradioBehavior resource set to True, then the 
widget field associated with this resource contains the widget ID of the last Tog- 
gleButton or ToggleButtonGadget to change from unselected to selected. The 
default value is the widget ID of the first child in the widget. 

XmNmnemonic 

This resource is only useful when XmNrowColumnType is set to 
XmMENU_OPTION. Specifies a single character which, when typed by the user, 
posts the associated Pulldown MenuPane. The character is underlined if it appears 
in the OptionMenu label, giving the user a visual cue that the character has special 
functionality associated with it. The default is no mnemonic. 

XmNnumColumns 

Specifies the number of minor dimension extensions that are made to accommodate 
the entries; this attribute is only meaningful when XmNpacking is set to 
XmPACKCOLUMN. 

For vertically-oriented RowColumn widgets, this attribute indicates how many 
columns are built; the number of entries per column are adjusted to maintain this 
number of columns, if possible. 

For horizontally-oriented RowColumn widgets, this attribute indicates how many 
rows are built. 

The default value is one. 
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XmNorientation 

Determines whether RowColumn layouts are row major or column major. In a 
column major layout, the children of the RowColumn are laid out in columns top to 
bottom within the widget. In a row major layout the children of the RowColumn 
are laid out in rows. XmVERTICAL resource value selects a column major layout. 
XmHORIZONTAL resource value selects a row major layout. 

The default value is XmVERTICAL, except when creating a MenuBar, when the 
default is XmHORIZONTAL. 

XmNpacking 

Specifies how to pack the items contained within a RowColumn widget. This can be 
set to XmPACK TIGHT, XmPACKCOLUMN or XmPACKNONE. When a 
RowColumn widget packs the items if contains, it determines its major dimension 
using the value of the XmNorientation resource. 

XmPACK_TIGHT indicates that given the current major dimension (e.g. vertical if 
XmNorientation is XmVERTICAL), entries are placed one after the other until the 
RowColumn widget must wrap. RowColumn wraps when there is no room left for 
a complete child in that dimension. Wrapping occurs by beginning a new row or 
column in the next available space. Wrapping continues, as often as necessary, until 
all of the children are laid out In the vertical dimension (columns), boxes are set to 
the same width; in the horizontal dimension (rows), boxes are set to the same 
depth. Each entry's position in the major dimension is left unaltered (e.g., XmNy is 
left unchanged when XmNorientation is XmVERTICAL); its position in the minor 
dimension is set to the same value as the greatest entry in that particular row or 
column. The position in the minor dimension of any particular row or column is 
independent of all other rows or columns. 

XmPACK COLUMN indicates that all entries are placed in identically sized boxes. 
The box is based on the largest height and width values of all the children widgets. 
The value of the XmNnumColumns resource determines how many boxes are 
placed in the major dimension, before extending in the minor dimension. 

XmPACK_NONE indicates that no packing is performed. The x and y attributes of 
each entry are left alone, and the RowColumn widget attempts to become large 
enough to enclose all entries. 

The default value is XmPACK_TIGHT except when building an OptionMenu or a 
RadioBox, where the default is XmPACK_COLUMN. 

XmNpopupEnabled 

Allows the menu system to enable keyboard input (accelerators and mnemonics) 
defined for the Popup MenuPane and any of its submenus. The Popup MenuPane 
needs to be informed whenever its accessibility to the user changes because posting 
of the Popup MenuPane is controlled by the application. The default value for this 
resource is True (keyboard input - accelerators and mnemonics - defined for the 
Popup MenuPane and any of its submenus is enabled). 

XmNradioAlwaysOne 

Forces the active ToggleButton or ToggleButtonGadget to be automatically selected 
after having been unselected (if no other toggle was activated), if True. If False, the 
active toggle may be unselected. The default value is True. This resource is only 
important when XmNradioBehavior is True. 

The application always has the freedom to add and subtract toggles from 
RowColumn regardless of the selected/unselected state of the toggle. The applica- 
tion also has the freedom to manage and unmanage toggle children of RowColumn 
at any time regardless of state. Because of these freedoms, there are cases in which 
it is possible for the application to create a RowColumn which has XmNra- 
dioAlwaysOne set to True and none of the toggle children selected. 

XmNradioBehavior 

Specifies a Boolean value that when True, indicates that the RowColumn widget 
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should enforce a RadioBox-type behavior on all of its children which are ToggleBut- 
tons or ToggleButtonGadgets. 

Two ToggleButton and ToggleButtonGadget resources are forced to specified 
values at creation time: XmNindicator is forced to XmONE_OF_MANY and 
XmNvisibleWhenOflf is forced to True. 

RadioBox behavior dictates that when one toggle is selected and another toggle is 
selected, the first toggle is unselected automatically. The default value is False, 
except when creating a RadioBox, when the default is True. 

XmNresizeHeight 

Requests a new height if necessary, when set to True. When set to False, the widget 
does not request a new height regardless of any changes to the widget or its chil- 
dren. 

XmNresizeWidth 

Requests a new width if necessary, when set to True. When set to False, the widget 
does not request a new width regardless of any changes to the widget or its children. 

XmNrowColumnType 

Specifies the type of RowColumn widget which is to be created. It is a non-standard 
resource that cannot be changed after it is set. If an application uses any of the con- 
venience routines, except XmCreateRowColumn, then this resource is automatically 
forced to the appropriate value by the convenience routine. If an application uses 
the Xt Intrinsics API to create its RowColumn widgets, then it must specify this 
resource itself. The set of possible settings for this resource are: 

• XmWORK AREA - the default. 

• XmMENUBAR. 

• XmMENU PULLDOWN. 

• XmMENUPOPUP. 

• XmMENUOPTION. 

This resource cannot be changed after the RowColumn widget is created. Any 
changes attempted through XtSetValues are ignored. 

XmNspacing 

Specifies the horizontal and vertical spacing between items contained within the 
RowColumn widget. The default value is one pixel, except for a horizontal Menu- 
Bar, which defaults to 0 pixels. 

XmNsubMenuId 

Specifies the widget ID for the Pulldown MenuPane to be associated with an 
OptionMenu. This resource is only useful when XmNrowColumnType is set to 
XmMENU OPTION. This resource must be specified at creation time for an 
OptionMenu to function properly; it is unused for all other RowColumn types. The 
default value is NULL. 

XmNunmapCallback 

Specifies a list of callbacks that is called after the window associated with the 
RowColumn widget has been unmapped. The callback reason is XmCR_Unmap. 
The default value is NULL. 

XmNwhichButton 

Specifies the mouse button to which a menu system is sensitive. The default for 
XmMENU POPUP is mouse button 3. The default for XmMENU OPTION and 
XmMENU~BAR is mouse button 1. This resource is not useful for RowColumn 
widgets of type XmWORK AREA and XmMENU PULLDOWN. 
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XmRowColumn Special Menu Resource 


Name 


Class 




Default 


Access 


XmNmenuCursor 


XmCCursor 


String 


arrow 


C 



XmNmenuCursor 

Sets a variable which controls the cursor which is used whenever this application 
posts a menu. This resource can only be specified once at application startup time, 
either by placing it within a defaults file or by using the -xrm command line argu- 
ment. 

Example: myProg -xrm "*menuCurson arrow" 

The menu cursor can also be selected programmatically by using the function 
XmSetMenuCursor. The following is a list of acceptable cursor names. If the appli- 
cation does not specify a cursor or if an invalid name is supplied, then the default 
cursor (an arrow pointing up and to the right) is used. 



Xcursor 


dotbox 


man 


sizing 


arrow 


double_arrow 


middlebutton 


spider 


based_arrow_down 


draftlarge 


mouse 


spraycan 


based arrowup 


draft'small 


pencil 


star 


boat 


drapedbox 


pirate 


target 


bogosity 


exchange 


plus 


tcross 


bottomleftcorner 


fleur 


question_arrow 


top_left_arrow 


bottomrightcorner 


gobbler 


right_ptr 


top_left_corner 


boUom_side 


gumby 


right_side 


top_right corner 


bottomtee 


handl 


righttee 


top_side 


boxspiral 


hand2 


rightbutton 


top tee 


center_ptr 


heart 


rtllogo 


trek 


circle 


icon 


sailboat 


ulangle 


clock 


iron_cross 


sbdownarrow 


umbrella 


coffeejnug 


leftjptr 


sb h double arrow 


ur angle 


cross" 


left_side 


sb'left arrow 


watch 


cross reverse 


lefftee 


sb_right_arrow 


xterm 


crosshair 


leftbutton 


sb_up arrow 




diamond cross 


Hangle 


sbvdoublearrow 




dot 


lrangle 


shuttle 





Inherited Resources 

RowColumn inherits behavior and resources from the following named superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 
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XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadcwColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XniNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallbadc 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadowThickness 


XmCShadowThickness 


short 


0 


CSG 


XmNtopShadowCblor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPDCELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 



Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPDCMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


dynamic 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


16 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


16 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 

XEvent * event; 

Widget widget; 

char * data; 

char * callbackstruct; 
} XmRowColumnCallbackStruct; 
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reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

The following fields apply only when the callback reason is XmCR_ACTTVATE; for all other 
callback reasons, these fields are set to NULL. The XmCRACTIVATE callback reason is 
only generated when the application has supplied an entry callback, which overrides any 
activation callbacks registered with the individual RowColumn items. 

widget Is set to the widget ID of the RowColumn item which has been 

activated. 

data Contains the client-data value supplied by the application when the 

RowColumn item's activation callback was registered. 

callbackstruct Points to the callback structure generated by the RowColumn item's 

activation callback. 

Behavior 

A RowColumn widget's behavior depends on its type (MenuBar, Popup MenuPane, etc.) 
and the type of menu system in which it resides (Pulldown, Popup, or Option). The specific 
mouse button depends on the XmNwhichButton resource. 

Default MenuBar 
<BtnlDown>: 

If the button event occurs within one of the MenuBar buttons, then the MenuBar is 
armed (if not already armed) and the submenu associated with the selected button 
is posted. By moving the mouse, the user is then able to access the MenuPanes 
attached to the MenuBar. 

If the button event does not occur within one of the MenuBar buttons and if the 
MenuBar is already armed, it is disarmed, and any visible MenuPanes are unposted; 
if the MenuBar is not already armed, then nothing occurs. 

<BtnlUp>: 

If the MenuBar is armed, then this event unposts all visible MenuPanes and then 
disarms the menubar. 

Default OptionMenu 
<BtnlDown>: 

When this event occurs within the selection area, the Pulldown MenuPane is posted. 
If this event occurs outside of the selection area and if the MenuPane is already 
posted, then the Pulldown MenuPane is unposted. 

<BtnlUp>: 

When this event occurs while the Pulldown MenuPane is posted, then it is unposted. 
< Return >: 

If this key is pressed while the focus is set to the selection area, then the Pulldown 
MenuPane is posted. 

Default Pulldown MenuPane from a Popup MenuPane 
<Btn3Down>: 

When this event occurs, the menu system disables traversal mode, and re-enters 
drag mode. Depending upon where the button down event occurs, certain portions 
of the visible set of MenuPanes are unposted. 

<Btn3Up>: 

When this event occurs within a gadget child of the MenuPane, the indicated child is 
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activated. If the child is not a CascadeButton (widget or gadget), then this also 
results in all visible MenuPanes being unposted. If the child is a CascadeButton 
(widget or gadget), then this results in the associated submenu being posted and 
traversal being enabled. When this event occurs outside of a gadget child, then all 
visible MenuPanes are unposted. 

< Return >: 

If this key is pressed while the focus is set to a gadget child of the MenuPane, then 
the indicated child is activated. If the child is not a CascadeButton (widget or 
gadget), then this also results in all visible MenuPanes being unposted. If the child 
is a CascadeButton (widget or gadget), then this results in the associated submenu 
being posted and traversal being enabled. 

< Escape >: 

This event imposts all visible MenuPanes. 

< Right >: 

If the current focus item is a CascadeButtonGadget, then this posts the associated 
Pulldown MenuPane and highlights the first accessible item within the Pulldown 
MenuPane. 

<Left>: 

If this occurs within a MenuPane which is a submenu of another MenuPane, then 
this causes the last MenuPane to be unposted and the focus to move to the previous 
MenuPane. 

<Up>: This moves the focus to the previous menu item; the previous menu item is defined 
as the widget which was created prior to the one which currently has the focus. 
Wrapping occurs, if necessary. 

< Down > : 

This moves the focus to the next menu item; the next menu item is defined as the 
widget which was created after the one which currently has the focus. Wrapping 
occurs, if necessary. 

Default Pulldown MenuPane from a MenuBar or from an OptionMenu 
<BtnlDown>: 

When this event occurs, the menu system disables traversal mode and re-enters drag 
mode. Depending upon where the button down event occurs, certain portions of 
the visible set of MenuPanes are unposted. 

<BtnlUp>: 

When this event occurs within a gadget child of the MenuPane, the indicated child is 
activated. If the child is not a CascadeButton (widget or gadget), then this also 
results in all visible MenuPanes being unposted. If the child is a CascadeButton 
(widget or gadget), then this results in the associated submenu being posted and 
traversal being enabled. When this event occurs outside of a gadget child, then all 
visible MenuPanes are unposted. 

<Return>: 

If this key is pressed while the focus is set to a gadget child of the MenuPane, then 
the indicated child is activated. If the child is not a CascadeButton (widget or 
gadget), then this also results in all visible MenuPanes being unposted. If the child 
is a CascadeButton (widget or gadget), then this results in the associated submenu 
being posted and traversal being enabled. 

< Escape >: 

This event unposts all visible MenuPanes. 

< Right >: 

If the current focus item is a CascadeButtonGadget, then this posts the associated 
Pulldown MenuPane and highlights the first accessible item within the Pulldown 
MenuPane. If the current focus item is not a CascadeButton, then the visible set of 
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MenuPanes are unposted, and the top level Pulldown MenuPane associated with the 
next MenuBar item is posted. 

<Left>: 

If this is occurs within a MenuPane which is a submenu of another MenuPane, then 
this event causes the last MenuPane to be unposted and the focus to move to the 
previous MenuPane. If this is occurs within a MenuPane which is connected directly 
to the MenuBar, then the visible set of MenuPanes are unposted, and the top level 
Pulldown MenuPane associated with the previous menubar item is posted. 

<Up>: This moves the focus to the previous menu item; the previous menu item is defined 
as the widget which was created prior to the one which currently has the focus. 
Wrapping occurs, if necessary. 

< Down > : 

This moves the focus to the next menu item; the next menu item is defined as the 
widget which was created after the one which currently has the focus. Wrapping 
occurs, if necessary. 

WorkArea 

<BtnlDown> 

If the button press occurred in a gadget child, it is dispatched to it. 
<BtnlUp> 

If the button press occurred in a gadget child, it is dispatched to it. 



Default Translations 



The following are the default translations for an OptionMenu: 
<BtnDown>: PopupBtnDownQ 



<BtnUp>: 
<Key>Returrc 



PopupBtnUp() 
MenuGadgetReturnO 



The following are the default translations for a Popup MenuPane: 



<BtnDown>: 
<BtnUp>: 

< Key > Return: 

< Key > Escape: 
<Unmap>: 
<FocusIn>: 
<FocusOut>: 
<EnterWindow>: 

< Key > Left: 

< Key > Right: 
<Key>Up: 
<Key>Down: 



PopupBtnDown() 

PopupBtnUp() 

MenuGadgetReturnO 

MenuGadgetEscape() 

MenuUnmapO 

MenuFocusIn() 

MenuFocusOut() 

MenuEnter() 

MenuGadgetTraverseLeft() 
MenuGadgetTraverseRightO 
MenuGadgetTraverseUp() 
MenuGadgetTraverseDovmO 



The following are the default translations are for a Pulldown MenuPane: 



<BtnDown>: 
<BtnUp>: 

< Key > Return: 

< Key > Escape: 
<Unmap>: 
<FocusIn>: 
<FocusOut>: 
<EnterWindow>: 

< Key > Left: 

< Key > Right: 



PulldownBtnDownO 

PulldownBtnUpO 

MenuGadgetReturnO 

MenuGadgetEscape() 

MenuUnmapO 

MenuFocusIn() 

MenuFocusOut() 

MenuEnterO 

MenuGadgetTraverseLeftO 
MenuGadgetTraverseRightO 
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<Key>Up: 
< Key > Downs 



MenuGadgetTraverseUpO 
MenuGadgetTraverseDownQ 



The following are the default translations for a MenuBan 



<BtnDown>: MenuBarBtnDown() 

<BtnUp>: MenuBarBtnUpO 

<Unmap>: MenuUnmapO 

<FocusIn>: MenuFocusIn() 

<FocusOut>: MenuFocusOut() 

<EnterWindow>: MenuEnterQ 



The following are the default translations for a WorkArea: 

<BtnlDown>: WorkAreaBtnDown() 
<BtnlUp>: WorkAreaBtnUpO 



Keyboard Traversal 

For information on keyboard traversal in a WorkArea, see the man page for 
XmManager(3X) and its sections on behavior and default translations. 

RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateRowColumn(3X), XmCreateMenuBar(3X), 
XmCreateOptionMenu(3X), XmCreatePopupMenu(3X), XmCreatePuUdownMenu(3X), 
XmCreateRadioBox(3X), XmGetMenuCursor(3X), XmLabel(3X), XmManager(3X), 
XmOptionButtonGadget(3X), XmOptionLab«lGadget(3X), XmSetMenuCursor(3X), 
XmMenuPosition(3X), and XmUpdateDisplay(3X). 
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NAME 

XmScale - the Scale widget class. 

SYNOPSIS 

#include <Xm/Scale.h> 

DESCRIPTION 

Scale is used by an application to indicate a value from within a range of values, and it allows the 
user to input or modify a value from the same range. 

A Scale has an elongated rectangular region similar to a ScrollBar. Inside this region, is a slider 
which indicates the current value along the Scale. The user can also modify the Scale's value by 
moving the slider within the rectangular region of the Scale. A Scale can also include a label set 
located outside the Scale region. These can indicate the relative value at various positions along 
the scale. 

A Scale can be either input/output or output only. An input/output Scale's value can be set by the 
application and also modified by the user by using the slider. An output-only Scale is used strictly 
as an indicator of the current value of something and cannot be modified interactively by the user. 
The Core resource XmNsensitive specifies whether or not the user can interactively modify the 
Scale's value. 

Classes 

Scale inherits behavior and resources from Core, Composite, Constraint, and XmManager 
classes. 

The class pointer is xmScaleWidgetClass. 
The class name is XmScale. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmScak Resource Set 




Class 




Default 




XmNdccinialPoints 


XmCDecimalPoints 


short 


0 


CSG 


AJniN QragL>a iipacx 


V«m/*yiLllKaj4r 


AtCa 1 ID8CK t .ISt 


NULL 


C 


VmKIfnHtT 1m* 

AnUNiontLJst 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


.auhn nigniigntMnitntgr 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNmgnlignri nickness 


XmCHighlightThickness 


short 


0 


CSG 


XfflNffla XI TTWffl 


XmCMaximum 


int 


100 


CSG 


XniNmmi mum 


XmOK^i m mwro 


int 


0 


CSG 


XmNoricntation 


XmOOnentation 


unsigned char 


Ym\/CDTirA T 


CSG 


XmNprocessingDircction 


XmCProcessingDirection 


unsigned char 




CSG 


XmNscaleHeight 


XmCScaleHeight 


Dime os ion 


o 


CSG 


XmNscaleWidth 


XmCScalcWidth 


Dimension 


0 


CSG 


XmNshowValue 


XmCShowValue 


Boolean 


False 


CSG 


XmNtitleString 


XmCTitleString 


XmString 


NULL 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNvalue 


XmCValue 


int 


0 


CSG 


XmNvalueChangedCallbadt 


XmCCallback 


XtCallbackList 


NULL 


C 



XmNdecimalPoints 

Specifies the number of decimal points to shift the slider value when displaying it. 
For example, a slider value of 2,350 and an XmdecimalPoints value of 2 would 
result in a display value of 2330. 

XmNdragCallback 

Specifies the list of callbacks that is called when the slider position changes as the 
slider is being dragged. The reason sent by the callback is XmCR_DRAG. 

XmNfontList 

Specifies the font list to use for the title text string specified by XmNtitleString. 

XmNhighlightOnEnter 

Specifies whether to draw the slider's border highlight on enter window events. 
This resource is ignored if the XmNtraversalOn resource is set to True. 

XmNhighlightThickness 

Specifies the size of the slider's border drawing rectangle used for enter window 
and traversal highlight drawing. 

XmNmaximum 

Specifies the slider's maximum value. 

XmNminimum 

Specifies the slider's minimum value. 

XmNorientation 

Displays Scale vertically or horizontally. This resource can have values of XmVERT- 
ICAL and XmHORIZONTAL. 

XmNprocessingDirection 

Specifies whether the value for XmNmaximum is on the right or left side of 
XmNminimum for horizontal Scales or above or below XmNminimum for vertical 
Scales. This resource can have values of XmMAXONTOP, 
XmMAX ON BOTTOM, XmMAX ON LEFT, and XmMAX ON RIGHT. 

XmNscaleHeight 

Specifies the height of the slider area. The value should be in the specified unit 
type (default is pixels). 

XmNscaleWidth 

Specifies the width of the slider area. The value should be in the specified unit type 
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(default is pixels). 
XmNshowValue 

Specifies if a label for the current slider value should be displayed next to the slider. 
If it is True, the current slider value is displayed. 

XmNtitleString 

Specifies the title text string to appear in the scale widget window. 

XmNtraversalOn 

Specifies whether the Scale's slider is to have traversal on for it. 

XmNvalue 

Specifies the slider's current position along the scale, between minimum and max- 
imum. 

XmNvalueChangedCallback 

Specifies the list of callbacks that is called when the value of the slider has changed. 
The reason sent by the callback is XmCR VALUE CHANGED. 

Inherited Resources 

Scale inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhdpCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNhighlightColar 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadooThickness 


XmCShadoWThickness 


short 


0 


N/A 


XmNtopShadowColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED_PDCMAP 


CSG 


XmNunitT/pe 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 




Type 


irawui 


Access 


XmNaccelerators 


XmCAocelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgrouixlPixniap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestrqyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappecIWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int reason; 
XEvent * event; 

int value; 
} XmScaleCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

value Is the new slider location value. 

Behavior 

<BtnlDovm>: 

Activates the interactive dragging of the slider if the button is pressed anywhere 
inside of the scale rectangle, including the slider. 

Buttonl < PtrMoved > : 

Moves the slider to the new position and calls the callbacks for XmNdragCallback if 
the button press occurs within the slider. 

<BtnlUp>: 

Calls the callbacks for XmNvalueChangedCallback if the button press occurs within 
the scale rectangle and if the slider position was changed. 

Default Translations 

The following are Scale's default translations: 

<BtnlDown>: Arm() 
<BtnlUp>: Activate() 
<EnterWindow>: Enter() 
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<FocusIn>: FocusIn() 
Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateScale(3X), XmManager(3X), 
XmScaleGetValue(3X), and XmScaleSetValue(3X). 
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NAME 

XmScaleGetValue - a Scale function that returns the current slider position. 

SYNOPSIS 

#include <Xm/Scale.h> 

void XmScaleGetValue (widget, value jeturri) 
Widget widget; 
int * value _retum; 

DESCRIPTION 

XmScaleGetValue returns the current slider position value displayed in the scale. 

widget Specifies the Scale widget ID. 

value jetum Returns the current slider position value. 

For a complete definition of Scale and its associated resources, see XmScale(3X). 

RELATED INFORMATION 
XmScale(3X). 
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NAME 

XmScaleSetValue - a Scale function that sets a slider value. 

SYNOPSIS 

#include <Xm/Scale.h> 

void XmScaleSetValue (widget, value) 
Widget widget; 
int value", 

DESCRIPTION 

XmScaleSetValue sets the slider value within the Scale widget 
widget Specifies the Scale widget ID. 

value Specifies the slider position along the scale. This sets the XmNvalue 

resource. 

For a complete definition of Scale and its associated resources, see XmScale(3X). 

RELATED INFORMATION 
XmScale(3X). 
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NAME 

XmScrollBar - the ScrolIBar widget class. 

SYNOPSIS 

#inchide <Xm/ScrollBar.h> 

DESCRIPTION 

The ScrolIBar widget allows the user to view data that is too large to be displayed at one time. 
ScrollBars are usually located beside or within the widget that contains the data to be viewed. 
When the user interacts with the ScrolIBar, the data within the other widget scrolls. 

A ScrolIBar consists of two arrows placed at each end of a rectangle. The rectangle is called the 
scroll region. A smaller rectangle, called the slider, is placed within the scroll region. The data is 
scrolled by selecting on either arrow or the scroll region, or by dragging the slider. When an 
arrow is selected, the slider within the scroll region will be moved in the direction of the arrow by 
an amount supplied by the application. If the mouse button is held down, the slider will continue 
to move at a constant rate. 

The ratio of the slider size and the scroll region size corresponds to the relationship between the 
size of the visible data and the total size of the data. For example, if ten percent of the data is visi- 
ble, the slider will occupy ten percent of the scroll region. This provides the user with a visual clue 
to the size of the invisible data. 

Classes 

ScrolIBar inherits behavior and resources from the Core and XmPrimitive classes. 
The class pointer is xmScrollBarWidgetClass. 
The class name is XmScrollBar. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmScrollBar Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdecreroent Callback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNdragCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNincrement 


XmCIncrement 


int 


1 


CSG 


XmNincrement Callback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNinitialDelay 


XmCInitialDelay 


int 


250 


CSG 


XmNmaximum 


XmCMaximum 


int 


0 


CSG 


XmNminimum 


XmCMinimum 


int 


0 


CSG 


XmNorientation 


XmCOrientation 


unsigned char 


XmVERTICAL 


CSG 


XmNpageDecrement Callback 


XmCCallback 


XtCallbackList 


NULL 


CSG 


XmNpagelncrement 


XmCPagelncrement 


int 


10 


C 


XmNpagelncrement Callback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNprocessingDirection 


XmCProcessingDirection 


unsigned char 


XmMAX ON BOTTOM 


CSG 


XmNrepeatDelay 


XmCRepeatDelay 


int 


50 


CSG 


XmNshowArrcws 


XmCShcwArrcws 


Boolean 


True 


CSG 


XmNsliderSize 


XmCSliderSize 


int 


10 


CSG 


XmNtoBottomCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNtcTopCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN value 


XmCValue 


int 


0 


CSG 


XmNvalueChangedCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmNdecrementCaUback 

Specifies the list of callbacks that is called when an arrow is selected which 
decreases the slider value by one increment. The reason sent by the callback is 
XmCR DECREMENT. 

XmNdragCallback 

Specifies the list of callbacks that is called on each incremental change of position 
when the slider is being dragged. The reason sent by the callback is XmCR_DRAG. 

XmNincrement 

Specifies the amount to move the slider when the corresponding arrow is selected. 

XmNincrementCallback 

Specifies the list of callbacks that is called when an arrow is selected which increases 
the slider value by one increment. The reason sent by the callback is 
XmCR INCREMENT. 

XmNinitialDelay 

Specifies the amount of time to wait (milliseconds) before starting continuous slider 
movement while an arrow or the scroll region is being pressed. 

XmNmaximum 

Specifies the slider's maximum value. 

XmNminimum 

Specifies the slider's minimum value. 

XmNorientation 

Specifies whether the ScrollBar is displayed vertically or horizontally. This resource 
can have values of XmVERTICAL and XmHORIZONTAL. 

XmNpageDecrementCallback 

Specifies the list of callbacks that is called when the slider area is selected and the 
slider value is decreased by one page increment. The reason sent by the callback is 
XmCRPAGEDECREMENT. 

XmNpagelncrement 

Specifies the amount to move the slider when selection occurs on the slide area. 
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XmNpagelncrementCallback 

Specifies the list of callbacks that is called when the slider area is selected and the 
slider value is increased by one page increment. The reason sent by the callback is 
XmCR PAGE INCREMENT. 

XmNprocessingDirection 

Specifies whether the value for XmNmaximum should be on the right or left side of 
XmNminimum for horizontal ScrollBars or above or below XmNminimum for verti- 
cal ScrollBars. This resource can have values of XmMAXONTOP, 
XmMAX ON BOTTOM, XmMAX ON LEFT, and XmMAX ON RIGHT. 

XmNrepeatDelay 

Specifies the amount of time to wait (milliseconds) between subsequent slider 
movements after the XmNinitialDelay has been processed. 

XmNshowArrows 

Specifies whether the arrows are displayed. 

XmNsIiderSize 

Specifies the size of the slider between the values of 0 and maximum - minimum. 

XmNtoBottomCallback 

Specifies the list of callbacks that are called when the user selects < Shift > mouse 
button 1 down and the pointer is in the bottom arrow (vertical ScrollBar) or the 
right arrow (horizontal ScrollBar). This callback sends as a value the maximum 
ScrollBar value minus the ScrollBar slider size. The slider location is not automati- 
cally repositioned. The reason sent by the callback is XmCR TO BOTTOM. 

XmNtoTopCallback 

Specifies the list of callbacks that are called when the user selects < Shift > mouse 
button 1 down and the pointer is in the top arrow (vertical ScrollBar) or the left 
arrow (horizontal ScrollBar). This callback sends as a value the minimum ScrollBar 
slider value. The slider location is not automatically repositioned. The reason sent 
by the callback is XmCRTOTOP. 

XmNvalue 

Specifies the slider's position between minimum and maximum. 

XmNvalueChangedCallback 

Specifies the list of callbacks that is called when the slider is released while being 
dragged; this is in place of XmNincrementCallback, XmNdecrementCallback, 
XmNpagelncrementCallback or XmNpageDecrementCallback when they do not 
have any callbacks attached. The reason sent by the callback is 
XmCRVALUECHANGED. 

Inherited Resources 

ScrollBar inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 
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XmPrimitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadcrwColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PDCMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCaUbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThidcness 


XmCHighlightThickness 


short 


0 


CSG 


XmNshadoWThickness 


XmCShadoWThickness 


short 


2 


CSG 


XrnNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPDCELS 


CSG 


XmNuserData 


XmCUserData 


caddr_t 


NULL 


CSG 




Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PDCMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PDCMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN height 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int reason; 
XEvent * event; 

int value; 
int pixel; 
} XmScroHBarCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 
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value Contains the new slider location value. 

pixel Is used only for XmNtoTopCallback and XmNtoBottomCallback. For hor- 

izontal ScrollBars, it contains the x coordinate of where the mouse button 
selection occurred. For vertical ScrollBars, it contains they coordinate. 



Behavior 

<BtnlDown>: 

(in arrow): Moves the slider one increment or decrement in the direction of the 
artop and calls the callbacks for XmNincrementCallback or XmNdecrementCall- 
back. The XmNvalueChangedCallbacks will be called if the XmNincrementCall- 
backs or XmNdecrementCallbacks are empty. 

(in scroll region): Moves the slider one page increment or page decrement depend- 
ing on which side of the slider is selected and calls the callbacks for XmNpagelncre- 
mentCallback or XmNpageDecrementCallback. The XmNvalueChangedCallbacks 
will be called if the XmNpagelncrementCallbacks or XmNpageDecrementCallbacks 

are empty. 

(in slider): Activates the interactive dragging of the slider. If the button is held 
down in either the arrows or scroll region longer than the XmNinitialDelay 
resource, then the slider is moved again by the same increment and the same call- 
backs are called. After the initial delay has been used, the time delay changes to the 
time defined by the resource XmNrepeatDelay. 

Buttonl < PtrMoved > : 

If the button press occurs within the slider, the subsequent motion events move the 
slider to the new position and the callbacks for XmNdragCallback are called. 

<BtnlUp>: 

If the button press occurs within the slider and the slider position is changed, then 
the callbacks for XmNvahieChangedCallback are called. 

Shift <BtnlDown>: 

When the pointer is in the top arrow (vertical ScrollBar) or the left arrow (horizon- 
tal ScrollBar), this mouse button press causes the callbacks for XmNtoTopCallback 
to be called. When the pointer is in the bottom arrow (vertical ScrollBar) or the 
right arrow (horizontal ScrollBar), this mouse button press causes the callbacks for 
XmNtoBottomCallback to be called. The slider does not change position. 

<Key>Up: 

For vertical ScrollBars, pressing the up arrow cursor key decrements the slider one 
unit and calls XmNdecrementCallback. The XmNvalueChangedCallbacks will be 
called if the XmNdecrementCallbacks are empty. 

<Key>Down: 

For vertical ScrollBars, pressing the down arrow cursor key increments the slider 
one unit and calls XmNincrementCallback. The XmNvalueChangedCallbacks will 
be called if the XmNincrementCallbacks are empty. 

<Key>Left: 

For horizontal ScrollBars, pressing the left arrow cursor key decrements the slider 
one unit and calls XmNdecrementCallback. The XmNvalueChangedCallbacks will 
be called if the XmNdecrementCallbacks are empty. 

<Key> Right: 

For horizontal ScrollBars, pressing the right arrow cursor key increments the slider 
one unit and calls XmNincrementCallback. The XmNvalueChangedCallbacks will 
be called if the XmNincrementCallbacks are empty. 



Default Translations 
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"Shift 'Ctrl 'Meta 'Alt <BtnlDown>: 

'Shift 'Ctrl 'Meta "Alt <BtnlUp>: 

'Shift 'Ctrl 'Meta 'Alt Buttonl<PtrMoved>: 

Shift 'Ctrl 'Meta 'Alt <BtnlDown>: 

Shift 'Ctrl 'Meta 'Alt <BtnlUp>: 

"Shift Ctrl 'Meta 'Alt <BtnlDown>: 

'Shift 'Ctrl 'Meta 'Alt <Key>Up: 

'Shift 'Ctrl 'Meta 'Alt < Key > Down: 

"Shift 'Ctrl 'Meta "Alt < Key > Left: 

'Shift "Ctrl 'Meta 'Alt < Key > Right: 

<EnterWindow>: 

< LeaveWindow > : 

<FocusIn>: 

<FocusOut>: 

<Unmap>: 

Shift < Key > Tab: 

<Key>Tab: 

Ctrl<Key>Tab: 



Select() 

Release() 

Moved() 

TopOrBottom() 

Release() 

GoToBottom() 

UpOrLeft(O) 

DownOrRight(O) 

UpOrLeft(l) 

DownOrRight(l) 

Enter() 

Leave() 

PrimitiveFocusIn() 

PrimitiveFocusOutO 

PrimitiveUnmapO 

PrimitivePrevTabGroupO 

PrimitiveNextTabGroupO 

PrimitiveNextTabGroupQ 



Keyboard Traversal 

If the XtNtraversalOn resource is set to True at either create time or during a call to XtSet- 
Values, the Manager superclass will automatically augment the Manager widget's transla- 
tions to support keyboard traversal. Refer to XmManager(3X) for a complete description of 
these translations. 

RELATED INFORMATION 

Core(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetValues(3X), and 
XmScrollBarSetValues(3X). 
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NAME 

XmScrollBarGetValues - a ScrollBar function that returns the ScrollBar's increment values and 
changes the slider's size and position. 



SYNOPSIS 

#include < Xm /ScrollBar.h > 

void XmScrollBarGetValues (widget, value jetum, slider jixe jetum, increment return, 



pagejncrementjeturn) 
Widget widget; 
int * value return; 

int * slider _size return; 

int * increment jetum ; 

int * pagejncrementjeturn; 



DESCRIPTION 

XmScrollBarGetValues returns the the ScrollBar's increment values and changes the slider's size 
and position. The scroll region is overlaid with a slider bar that is adjusted in size and position 
using the main ScrollBar or set slider function attributes. 



widget 
value return 



slider size return 



increment jeturn 
pagejncrementjeturn 



Specifies the ScrollBar widget ID. 

Returns the ScrollBar's slider position between the 
XmNminimum and XmNmaximum resources to the 
ScrollBar widget. 

Returns the size of the slider as a value between zero and 
the absolute value of XmNmaximum minus XmNminimum. 
The size of the slider varies, depending on how much of the 
slider scroll area it represents. 

Returns the amount of button increment and decrement. 
Returns the amount of page increment and decrement. 



For a complete definition of ScrollBar and its associated resources, see XmScrollBar(3X). 



RETURN VALUE 

Returns the ScrollBar's increment values and changes the slider's size and position. 



RELATED INFORMATION 
XmScrollBar(3X). 
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NAME 

XmScroIIBarSetValues - a ScrollBar function that changes ScrollBar's increment values and the 
slider's size and position. 



SYNOPSIS 

#include <Xm/ScrollBar.h> 



void XmScroIIBarSetValues (widget, value, slider _size, increment, pagejncrement, notify) 

Widget widget; 

int value; 

bit slider jize\ 

int increment, 

int pagejncrement; 

Boolean notify; 



DESCRIPTION 

XmSetScrollBarValues changes the ScrollBar's increment values and the slider's size and position. 
The scroll region is overlaid with a slider bar that is adjusted in size and position using the main 
ScrollBar or set slider function attributes. 



widget 
value 



slider size 



increment 



pagejncrement 



notify 



Specifies the ScrollBar widget ID. 

Specifies the ScrollBar's slider position between XmNminimum and 
XmNmaximum. The resource name associated with this argument is 
XmN value. 

Specifies the size of the slider as a value between zero and the absolute 
value of XmNmaximum minus XmNminimum. The size of the slider 
varies, depending on how much of the slider scroll area it represents. 
This sets the XmNsliderSize resource associated with ScrollBar. 

Specifies the amount of button increment and decrement. If this argu- 
ment is not zero, the ScrollBar widget automatically adjusts the slider 
when an increment or decrement action occurs. This sets the XmN in- 
crement resource associated with ScrollBar. 

Specifies the amount of page increment and decrement. If this argu- 
ment is not zero, the ScrollBar widget automatically adjusts the slider 
when an increment or decrement action occurs. This sets the 
XmNpagelncrement resource associated with ScrollBar. 

Specifies a Boolean value that when True, indicates a change in the 
ScrollBar value and that the ScrollBar widget automatically activates the 
XmNvalueChangedCallback with the recent change. If False, no change 
in the ScrollBar's value has occurred, and XmNvalueChangedCallback is 
not activated. 



For a complete definition of ScrollBar and its associated resources, see XmScrollBar(3X). 



RELATED INFORMATION 
XmScrollBar(3X). 
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NAME 

XmScroIled Window - the ScrolIedWindow widget class. 

SYNOPSIS 

#include <Xm/ScroUedW.h> 

DESCRIPTION 

The ScrolIedWindow widget combines one or more ScrollBar widgets and a viewing area to imple- 
ment a visible window onto some other (usually larger) data display. The visible part of the win- 
dow can be scrolled through the larger display by the use of ScrollBars. 

To use ScrolIedWindow, an application first creates a ScrolIedWindow widget, any needed 
ScrollBar widgets, and a widget capable of displaying any desired data as the work area of Scrol- 
IedWindow. ScrolIedWindow will position the work area widget and display the ScrollBars if so 
requested. When the user performs some action on the ScrollBar, the application will be notified 
through the normal ScrollBar callback interface. 

ScrolIedWindow can be configured to operate in an automatic manner so that it performs all 
scrolling and display actions with no need for application program involvement. It can also be 
configured to provide a minimal support framework in which the application is responsible for 
processing all user input and making all visual changes to the displayed data in response to that 
input. 

When ScrolIedWindow is performing automatic scrolling it will create a clipping window. Con- 
ceptually, this window becomes the view port through which the user examines the larger underly- 
ing data area. The application simply creates the desired data, then makes that data the work area 
of the ScrolIedWindow. When the user moves the slider to change the displayed data, the 
workspace is moved under the viewing area so that a new portion of the data becomes visible. 

There are instances where it is impractical for an application to create a large data space and sim- 
ply display it through a small clipping window. An example of this is a text editor - there would 
be an undesirable amount of overhead involved with creating a single data area that consisted of a 
large file. The application would want to use the concept of a ScrolIedWindow (a small viewport 
onto some larger data), but would want to be notified when the user scrolled the viewport so it 
could bring in more data from storage and update the display area. For these cases the Scrol- 
IedWindow can be configured so that it provides only visual layout support. No clipping window 
is created, and the application must maintain the data displayed in the work area, as well as 
respond to user input on the ScrollBars. 

Classes 

ScrolIedWindow inherits behavior and resources from Core, Composite, Constraint, and 
XmManager Classes. 

The class pointer is xmSc rolled WindowWidgetClass. 
The class name is XmScrolledWindow. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmScrolkdWindow Resource Set 


Name 


Claw 


Type 


Default 


Access 


XmNclipWindow 


XnCClipWindow 


Widget 


NULL 


G 


XmNhorizontalScrollBar 


XmCHorizontalScrollBar 


Widget 


NULL 


CSG 


XmNscrollBarDisplayPolicy 


XmCScrollBarDisplayPoUcy 


unsigned char 


XmSTATIC 


CG 


XmNscrollBarPlacement 


XmCScraOBarPIacemeth 


unsigned char 


XmBOTTOM RIGHT 


CSG 


XmNscroUedWindowMarginHeight 


XmCScroUedWindowMarginHeight 


Dimension 


0 


CSG 


XmNscroUedWindcwMarginWidth 


XmCScroUedWindcwMarginWidth 


Dimension 


0 


CSG 


XmNscrollingPolicy 


XmCScrollingPolicy 


unsigned char 


XmAPPUCATION DEFINED 


CG 


XmNspacing 


XmCSpacing 


Dimension 


4 


CSG 


XmNverticalScrollBar 


XmCVerticalScrollBar 


Widget 


NULL 


CSG 


XmNvisualPolicy 


XmCVisualPolicy 


unsigned char 


XmVARIABLE 


CG 


XmNworkWindow 


XmCWorkWindow 


Widget 


NULL 


CSG 



XmNcIipWindow 

Specifies the widget ID of the clipping area. This is automatically created by Scrol- 
ledWindow when the XmNvisualPolicy resource is set to XmCONSTANT and can 
only be read by the application. Any attempt to set this resource to a new value will 
cause a warning message to be printed by the scrolled window. If the XmNvisual- 
Policy resource is set to XmVARIABLE, this resource is set to NULL, and no clip- 
ping window is created. 

XmNhorizontalScrollBar 

Specifies the widget ID of the horizontal ScrollBar. 

XmNscrollBarDisplayPolicy 

Controls the automatic placement of the ScrollBars. If it is set to XmAS_NEEDED 
and if XmNscrollingPolicy is set to XmAUTOMATIC, ScrollBars will only be 
displayed if the workspace exceeds the clip area in one or both dimensions. A 
resource value of XmSTATIC will cause the ScrolledWindow to display the 
ScrollBars whenever they are managed, regardless of the relationship between the 
clip window and the work area. This resource must be XmSTATIC when 
XniNscrolIingPolicy is XmAPPLICATION_DEFINED. 

XmNscrollBarPlacement 

Specifies the positioning of the ScrollBars in relation to the work window. The fol- 
lowing are the values: 

• XmTOPLEFT - The horizontal ScrollBar is placed above the work window 
and the vertical ScrollBar to the left of the work window. 

• XmBOTTOM LEFT - The horizontal ScrollBar is placed below the work win- 
dow and the vertical ScrollBar to the left of the work window. 

• XmTOP RIGHT - The horizontal ScrollBar is placed above the work window 
and the vertical ScrollBar to the right of the work window. 

• XmBOTTOM RIGHT - The horizontal ScrollBar is placed below the work 
window and the vertical ScrollBar to the right of the work window. 

XmNscroUedWindowMarginHeight 

Specifies the margin height on the top and bottom of the ScrolledWindow. 

XmNscrolledWindowMarginWidth 

Specifies the margin width on the right and left sides of the ScrolledWindow. 

XmNscrollingPolicy 

Performs automatic scrolling of the work area with no application interaction. If the 
value of this resource is XmAUTOMATIC, ScrolledWindow automatically creates 
the ScrollBars; attaches callbacks to the ScrollBars; sets the visual policy to 
XmCONSTANT; and automatically moves the work area through the clip window in 
response to any user interaction with the ScrollBars. An application can also add its 
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own callbacks to the ScrollBars. This allows the application to be notified of a 
scroll event without having to perform any layout procedures. 

NOTE: Since the Scrolled Window adds callbacks to the ScrollBars, an application 
should not perform an XtRemoveAllCallbacks on any of the ScrollBar widgets. 

When XmNscroUingPolicy is set to XmAPPLICATIONDEFINED, the application 
is responsible for all aspects of scrolling. The ScrollBars must be created by the 
application, and it is responsible for performing any visual changes in the work area 
in response to user input 

This resource must be set to the desired policy at the time the ScrolledWindow is 
created. It cannot be changed through Set Values. 

XmN spacing 

Specifies the distance that separates the ScrollBars from the work window. 

XmNverticalScrollBar 

Specifies the widget ID of the vertical ScrollBar. 
XmNvisualPolicy 

Grows die ScrolledWindow to match the size of the work area, or it can be used as 
a static viewport onto a larger data space. If the visual policy is XmVARIABLE, the 
ScrolledWindow will force the ScrollBar display policy to XmSTATIC and allow the 
work area to grow or shrink at any time and will adjust its layout to accommodate 
the new size. When the policy is XmCONSTANT, the work area will be allowed to 
grow or shrink as requested, but a clipping window will force the size of the visible 
portion to remain constant. The only time the viewing area can grow is in response 
to a resize from the ScrolledWindow's parent. 

NOTE: This resource must be set to the desired policy at the time the ScrolledWin- 
dow is created. It cannot be changed through SetValues. 

XmNworkWindow 

Specifies the widget ID of the viewing area. 

Inherited Resources 

ScrolledWindow inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadcwPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadouThickness 


XmCShadoWThidcness 


short 


0 


CSG 


XmNtopShadowColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNunitType 


XmCUniffype 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrj 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccclcratois 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XniNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPEClFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolonnap 


XmCColormap 


Colormap 


XtCbpyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCbpyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


c 


XmNheight 


XmCHeight 


Dimension 


o 


CSG 


XmNmappedWhenManaged 


XinCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

ScrolledWindow defines no new callback structures. The application must use the ScrollBar 
callbacks to be notified of user input. 

Behavior 

ScrolledWindow makes extensive use of the XtQueryG«ometry functionality to facilitate 
geometry communication between application levels. In the XmAPPLICATION_DEFINED 
scrolling policy, the WorkWindow's query procedure is called by the ScrolledWindow when- 
ever the ScrolledWindow is going to change its size. The widget calculates the largest possi- 
ble workspace area and passes this size to the WorkWindow widget's query procedure. The 
query procedure can then examine this new size and determine if any changes are necessary, 
such as managing or unmanaging a ScrollBar. The query procedure performs whatever 
actions that it needs and then returns to the ScrolledWindow. The ScrolledWindow then 
examines the ScrollBars to see which (if any) are managed, allocates a portion of the visible 
space for them, and resizes the WorkWindow to fit in the rest of the space. 

When the scrolling policy is XmCONSTANT, the ScrolledWindow can be queried to return 
the optimal size for a given dimension. The optimal size is defined to be the size that would 
just enclose the WorkWindow. By using this mechanism, an application can size the Scrol- 
ledWindow so that it only needs to display a ScrollBar for one dimension. When the 
ScrolledWindow's query procedure is called via XtQueryGeometry, the request is examined 
to see if the width or height has been specified. If so, the routine uses the given dimension 
as the basis for its calculations. It will determine the minimum value for the other dimen- 
sion that will just enclose the WorkWindow, fill in the appropriate elements in the reply 
structure, and return to the calling program. Occasionally, using the specified width or 
height and the other minimum dimension would result in neither ScrollBar appearing. 
When this happens, the query procedure will set both the width and height fields, indicating 
that in this situation the ideal size would cause a change in both dimensions. If the calling 
application sets both the width and height fields, the ScrolledWindow will determine the 
minimum size for both dimensions and return those values in the reply structure. 

Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 
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RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmCreateScrolledWindow(3X), XmManager(3X), 
and XmScrolIedWindowSctAreas(3X). 
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NAME 

XmScrolledWindowSetAreas - a Scrolled Window function that adds or changes a window work 
region and a horizontal or vertical ScrollBar widget to the Scrolled Window widget. 



SYNOPSIS 

#include <Xm/ScroIledW.h> 



void XmScrolledWindowSetAreas (widget, horizontal jcroUbar, vertical jcrollbar, workjegion) 
Widget widget; 
Widget horizontal jcrollbar; 
Widget vertical jcrollbar, 
Widget workjegion; 



DESCRIPTION 

XmScrolledWindowSetAreas adds or changes a window work region and a horizontal or vertical 
ScrollBar widget to the ScrolledWindow widget for the application. Each widget is optional and 
may be passed as NULL. 



widget 

horizontal scrollbar 



vertical scrollbar 



workjegion 



Specifies the ScrolledWindow widget ID. 

Specifies the ScrollBar widget ID for the horizontal ScrollBar to 
be associated with the ScrolledWindow widget. Set this ID only 
after creating an instance of the ScrolledWindow widget. The 
resource name associated with this argument is XmNhorizontal- 
ScrollBar. 

Specifies the ScrollBar widget ID for the vertical ScrollBar to be 
associated with the ScrolledWindow widget. Set this ID only after 
creating an instance of the ScrolledWindow widget. The resource 
name associated with this argument is XmNverticalScrolIBar. 

Specifies the widget ID for the work window to be associated with 
the ScrolledWindow widget. Set this ID only after creating an 
instance of the ScrolledWindow widget. The attribute name asso- 
ciated with this argument is XmNworkWindow. 



For a complete definition of ScrolledWindow and its associated resources, see 
XmScrolledWindow(3X). 



RELATED INFORMATION 

XmScrolled Window(3X) . 
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NAME 

XmSelectionBox - the SelectionBox widget class. 

SYNOPSIS 

#include <Xm/SelectioB.h> 

DESCRIPTION 

SelectionBox is a general dialog widget which allows the user to select one item out of a list of 
items. A SelectionBox includes the following: 

• A scrolling list of alternatives. 

• An editable text field for the selected alternative. 

• Labels for the list and text field. 

• Three buttons. 

The default button labels are OK, Cancel, and Help. An Apply button is created unmanaged and 
may be explicitly managed as needed. One additional WorkArea child may be added to the Selec- 
tionBox after creation. 

The user can select an item in two ways: by scrolling through the list of items and selecting the 
desired item or by entering the item name directly into the text edit area. Selecting an item from 
the list will cause that item name to appear in the selection text edit area. 

The user may select a new item as many times as desired. The item is not actually selected until 
the user presses the OK PushButton. 

Classes 

SelectionBox inherits behavior and resources from Core, Composite, Constraint, 
XmManager and XmBulletinBoard Classes. 

The class pointer is xmSelectionBoxWidgetClass. 

The class name is XmSelectionBox. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmSekctionBox Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNapplyCallback 


XmCCaUbadt 


XtCallbackList 


NULL 


C 


XmNapplyLabelString 


XmCApplyLabelString 


XmString 


"Apply" 


CSG 


XmNcancelCaUback 


XmCCallback 


XtCallbackList 


NULL 


CSG 


XmNcancelLabelString 


XmCXmString 


XmString 


"Cancel" 


CSG 


XmNdialogfype 


XmCDialogType 


unsigned char 


dynamic 


CG 


XmNhelpLabelString 


XmCXmString 


XmString 


"Help" 


CSG 


XmNlistltemCount 


XmCItemCovmt 


int 


0 


CSG 


XmNlistltems 


XmCItems 


XmStringList 


NULL 


CSG 


XmNlistLabelString 


XmCXmString 


XmString 


NULL 


CSG 


XinNlistVisibleltemCount 


XmCVisibleltemCount 


int 


6 


CSG 


XmNminimizeButtons 


XmCMinimizeButtons 


Boolean 


False 


CSG 


XmNmustMatch 


XmCMust Match 


Boolean 


False 


CSG 


XmNnoMatchCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNckCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNokLabelString 


XmCXmString 


XmString 


"OK" 


CSG 


XmNselectionLabelString 


XmCXmString 


XmString 


"Selection" 


CSG 


XmNtextAccelerators 


XmCTextAccelerators 


XtTranslations 


see below 


C 


XmNtextColumns 


XmCText Columns 


int 


20 


CSG 


XmNtextString 


XmCTextString 


XmString 


NULL 


CSG 



XmNapplyCallback 

Specifies the list of callbacks that is called when the user clicks on the Apply button. 
The callback reason is XmCRAPPLY. 

XmNapplyLabelString 

Specifies the string label for the Apply button. 

XmNcancelCaUback 

Specifies the list of callbacks that is called when the user clicks on the Cancel but- 
ton. The callback reason is XmCRCANCEL. 

XmNcancelLabelString 

Specifies the string label for the Cancel button. 

XmNdialogType 

Determines the set of SelectionBox children widgets which are created and 
managed at initialization. The following are possible values: 

• XmDIALOG_PROMPT - the list and list label are not created, and the Apply 
button is unmanaged. 

• XmDIALOG SELECTION - all standard children are created and managed 
except the Apply button. 

• XmDIALOG_WORKAREA - all standard children are created and managed. 

If the parent of the SelectionBox is a DialogShell, the default is 
XmDIALOG SELECTION; otherwise, the default is XmDIALOG WORK AREA. 
XmCreatePromptDialog and XmCreateSelectionDialog set and append this 
resource to the creation argtist supplied by the application. This resource cannot be 
modified after creation. 

XmNhelpLabelString 

Specifies the string label for the Help button. 

XmNlistltems 

Specifies the items in the SelectionBox list 
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XmNlistltemCount 

Specifies the number of items in the SelectionBox list. 

XmNlistLabelString 

Specifies the string label to appear above the SelectionBox list containing the selec- 
tion items. 

XmNIistVisibleltemCount 

Specifies the number of items displayed in the SelectionBox list. 

XmNminimizeButtons 

Sets the buttons to the width of the widest button and height of the tallest button if 
False. If True, button width and height are not modified. 

XmNmu stMatch 

Specifies whether or not the selection widget should check if the user's selection in 
the text edit field has an exact match in the SelectionBox list If the selection does 
not have an exact match, and XmNmustMatch is True, the XmNnoMatchCallback 
is activated. If the selection does have an exact match, then either XmNapplyCall- 
back or XmNokCallback is activated. 

XmNnoMatchCallback 

Specifies the list of callbacks that is called when the user makes a selection from the 
text edit field that does not have an exact match with any of the items in the list box. 
The callback reason is XmCRNOMATCH. 

XmNokCallback 

Specifies the list of callbacks that is called when the user clicks the OK button. The 
callback reason is XmCR_OK 

XmNokLabelString 

Specifies the string label for the OK button. 

XmNselectionLabelString 

Specifies the string label for the selection text edit field. 

XmNtextAccelerators 

Specifies translations added to the Text widget child of the SelectionBox. The 
default includes bindings for the up and down keys for auto selection of list items; it 
also includes the normal accelerator translations defined by BulletinBoard for dia- 
log components. 

XmNtextColumns 

Specifies the number of columns in the Text widget. 

XmNtextString 

Specifies the text in the text edit selection field. 

Inherited Resources 

SelectionBox inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 
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XmBuUetin Board Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNallowOverlap 


XmCAllowOverlap 


Boolean 


True 


CSG 


XmNautoUnmanage 


XmCAutoUnmanage 


Boolean 


True 


CSG 


XmNbuttonFontList 


XmCButtonFontList 


XmFontList 


NULL 


CSG 


XmNcancelButton 


XmCWidget 


Widget 


Cancel button 


SG 


XmNdefaultButton 


XmCWidget 


Widget 


OK button 


SG 


XmNdefaultPosition 


XmCDefaultPosition 


Boolean 


True 


CSG 


XmNdialogStyle 


XmCDialogStyle 


unsigned char 


dynamic 


CSG 


XmNdialogTitle 


XmCXmString 


XmString 


NULL 


CSG 


XmNfocusCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNlabelFontList 


XmCLabelFontList 


XmFontList 


NULL 


CSG 


XmNmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


10 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


10 


CSG 


XmNnoResize 


XmCNoResize 


Boolean 


False 


CSG 


XmNresizePolicy 


XmCResizePolicy 


unsigned char 


XmRESIZE ANY 


CSG 


XmNshadoWfype 


XmCShadoWIype 


unsigned char 


XmSHADOW OUT 


CSG 


XmNstringDirect ion 


XmCStringDirection 


XmStringDirection 


XmSTRINGDIRECTIONLTOR 


CSG 


XtnNtextFontList 


XmCTextFontList 


XmFontList 


NULL 


CSG 


XmNtextTranslations 


XmCTranslations 


XtTranslations 


NULL 


C 


XmNunmapCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmManager Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmN highlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNshadowThickness 


XmCShadoWThickness 


short 


dynamic 


CSG 


XmNtopShadowColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



Composite Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNinsertPosition 


XmCInsertPosition 


XmRFunction 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XinCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 

XEvent * event; 

XmString value; 

int length; 
} XmSelectionBoxCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

value Indicates the XmString value selected by the user from the SelectionBox list 

or entered into the SelectionBox text field. 

length Indicates the size in bytes of the XmString value. 

Behavior 

The following is a summary of the behavior of SelectionBox. 

< OK Button Activated > : 

When the OK button is activated, the callback XmNokCallback is called. The rea- 
son is XmCR OK. When an invalid selection is made and it does not match any 
items in the list, the callback for XmNnoMatchCallback is called if XmNmustMatch 
is also True. The callback reason is XmCR_NO_MATCH. 

< Apply Button Activated >: 

When the Apply button is activated, the callback XmNappIyCallback is called. The 
callback reason is XmCR_APPLY. When an invalid selection is made and it does 
not match any items in the list, the callback for XmNnoMatchCallback is called, if 
XmNmustMatch is also True. The callback reason is XmCRNOMATCH. 

< Cancel Button Activated > : 

When the Cancel button is activated, the callback XmNcancelCallback is called. 
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The callback reason is XmCRCANCEL. 

< Help Button Activated > or < Key > Fl: 

When the Help button or Function key 1 is pressed, the callbacks for XmNhelpCall- 
back are called. 

< Default Button Activated > or < Key > Return: 

When the default button or return key is pressed, the corresponding callback is 
called (XmNokCallback, XmNapplyCallback, XmNcancelCallback, or XmNhelp- 
Callback). 

<Key>Up or < Key > Down; 

When the up or down key is pressed within the Text subwidget of the SelectionBox, 
the text value is replaced with the previous or next item in the List subwidget. 

<FocusIn>: 

When a Focusln event is generated on the widget window, the callbacks for 
XmNfocusCallback are called. 

<MapWindow>: 

When a SelectionBox that is the child of a DialogShell is mapped, the callbacks for 
XmNmapCallback are invoked. When a SelectionBox that is not the child of a Dia- 
logShell is mapped, the callbacks are not invoked. 

< UnmapWindow > : 

When a SelectionBox that is the child of a DialogShell is unmapped, the callbacks 
for XmNunmapCallback are invoked. When a SelectionBox that is not the child of 
a DialogShell is unmapped, the callbacks are not invoked. 



Default Translations 

The following are the default translations defined for SelectionBox widgets: 



<EnterWindow>: Enter () 

< Focusln >: FocusIn() 
<BtnlDown>: Arm() 
<BtnlUp>: Activate() 
<Key>Fl: Help() 

< Key > Return: Return() 
<Key>KPEnten ReturnO 



Default Accelerators 

The following are the default accelerator translations added to the descendants of a Selec- 
tionBox 



#override 

<Key>Fl: Help() 

< Key > Return: Return() 

<Key>KP Enter: ReturnO 



Default Text Accelerators 

The following are the default accelerators added to the Text child of the SelectionBox: 



#override 
<Key>Up: 

< Key > Down: 
<Key>Fl: 

< Key > Return: 
<Key>KP_Enten 



UpOrDown(O) 

UpOrDown(l) 

Help() 

ReturnO 

ReturnO 
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Keyboard Traversal 

For information on keyboard traversal, see the man page for XmManager(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateSelectionBox(3X), 
XmCreateSelectionDialog(3X), XmCreatePromptDiaIog(3X), XmManager(3X), and 
XmSelectionBoxGetChiId(3X). 
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NAME 

XmSelectionBoxGetChild - a SelectionBox function that is used to access a component 

SYNOPSIS 

#include <Xm/SelectioB.h> 

Widget XmSelectionBoxGetChild (widget, child) 

Widget widget; 
unsigned char child; 

DESCRIPTION 

XmSelectionBoxGetChild is used to access a component within a SelectionBox. The parameters 
given to the function are the SelectionBox widget and a value indicating which child to access. 

widget Specifies the SelectionBox widget ID. 

child Specifies a component within the SelectionBox. The following are legal values for 

this parameter: 

• XmDIALOGAPPLYBUTTON. 

• XmDIALOG CANCEL BUTTON. 

• XmDIALOG DEFAULT BUTTON. 

• XmDIALOG HELP BUTTON. 

• XmDIALOGLIST. 

• XmDIALOG LIST LABEL. 

• XmDIALOG OK BUTrON. 

• XmDIALOG SELECTION LABEL. 

• XmDIALOGSEPARATOR. 

• XmDIALOG TEXT. 

• XmDIALOGWORKAREA. 

For a complete definition of SelectionBox and its associated resources, see XmSelectionBox(3X). 

RETURN VALUE 

Returns the widget ID of the specified SelectionBox child. 

RELATED INFORMATION 

XmSelectionBox(3X). 
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NAME 

XmSeparator - the Separator widget class. 

SYNOPSIS 

#include <Xm/Separator.h> 

DESCRIPTION 

Separator is a primitive widget which separates items in a display. Several different line drawing 
styles are provided, as well as horizontal or vertical orientation. 

The Separator line drawing is automatically centered within the height of the widget for a horizon- 
tal orientation and centered within the width of the widget for a vertical orientation. An XtSet- 
Values with a new XmNseparatorType will resize the widget to its minimal height (for horizontal 
orientation) or its minimal width (for vertical orientation) unless height or width is explicitly set in 
the XtSet Values call. 

Separator does not draw shadows. The Primitive resource XmNshadowThickness is used for the 
Separator's thickness when XmNshadowType is XmSHADOW ETCHED IN or 
XmSHADO W_ETC H EDOUT. 

Separator does not highlight and allows no traversing. The primitive resource XmNtraversalOn is 
forced to False. 

The XmNseparatorType of XmNO_LINE provides an escape to the application programmer who 
needs a different style of drawing. "A pixmap the height of the widget can be created and used as 
the background pixmap by building an argument list using the XmNbackgroundPixmap argument 
type as defined by Core. Whenever the widget is redrawn, its background will be displayed con- 
taining the desired separator drawing. 

Classes 

Separator inherits behavior and resources from Core and XmPrimitive Classes. 
The class pointer is xmSeparatorWidgetClass. 
The class name is XmSeparator. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmSeparator Resource Set 


Name 


Class 


Type 


Default 


Access 


XmN margin 


XmCMargin 


short 


0 


CSG 


XmNorientation 


XmCOrientation 


unsigned char 


XmHORIZONTAL 


CSG 


XmNseparatorType 


XmCSeparatorType 


unsigned char 


XmSHADOW ETCHED IN 


CSG 



XmNmargin 

Specifies the space on the left and right sides between the border of the Separator 
and the line drawn for horizontal orientation. For vertical orientation, specifies the 
space on the top and bottom between the border of the Separator and the line 
drawn. 
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XmNorientation 

Displays Separator vertically or horizontally. This resource can have values of 
XmVERTICAL and XmHORIZONTAL. 

XmNseparatorType 

Specifies the type of line drawing to be done in the Separator widget. 

• XmSINGLE LINE - single line. 

• XmDOUBLE LINE - double line. 

• XmSINGLE DASHED LINE - single-dashed line. 

• XmDOUBLE DASHED LINE - double-dashed line. 

• XmNOLINE - no line. 

• XmSHADOW_ETCHED_IN - double line giving the effect of a line etched into 
the window. The thickness of the double line is equal to the value of XmNsha- 
dowThickness. For horizontal orientation, the top line is drawn in XmNtopSha- 
dowColor and the bottom line is drawn in XmNbottomShadowColor. For verti- 
cal orientation, the left line is drawn in XmNtopShadowColor and the right line 
is drawn in XmNbottomShadowColor. 

• XmSHADOW_ETCHED_OUT - double line giving the effect of an etched line 
coming out from the window. The thickness of the double line is equal to the 
value of XmNshadowThickness. For horizontal orientation, the top line is drawn 
in XmNbottomShadowColor and the bottom line is drawn in XmNtopSha- 
dowColor. For vertical orientation, the left line is drawn in XmNbottomSha- 
dowColor and the right line is drawn in XmNtopShadowColor. 

Inherited Resources 

Separator inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



XmPrimitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforeground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNhighlight Color 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlightThidcness 


XmCHighlightThickness 


short 


0 


CSG 


XmNshadowThickness 


XmCShadowTbickness 


short 


2 


CSG 


XmNtopShadowColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPKELS 


CSG 


XmNuserData 


XmCUserDala 


caddr t 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNacoelerators 


XmCAcceleratora 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCaUbadc 


XtCallbadcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XmCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmN translations 


XmCTrenslatkms 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmPrimitive(3X) and its sec- 
tions on behavior and default translations. 



RELATED INFORMATION 

Core(3X), XmCreateSeparator(3X), and XmPrimitive(3X). 
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NAME 

XmSeparatorGadget - the SeparatorGadget widget class. 

SYNOPSIS 

#include <Xm/SeparatoG.h> 

DESCRIPTION 

SeparatorGadget separates items in a display. Several line drawing styles are provided, as well as 
horizontal or vertical orientation. 

Lines drawn within the SeparatorGadget are automatically centered within the height of the 
gadget for a horizontal orientation and centered within the width of the gadget for a vertical orien- 
tation. An XtSetValues with a new XmNseparatorType will resize the widget to its minimal height 
(for horizontal orientation) or its minimal width (for vertical orientation) unless height or width is 
explicitly set in the XtSetValues call. 

SeparatorGadget does not draw shadows. The Gadget resource XmNshadowThickness is used for 
the SeparatorGadget's thickness when XmNshadowType is XmSHADOW ETCHED IN or 
XmSHADOWETCHEDOUT. 

SeparatorGadget does not highlight and allows no traversing. The Gadget resource XmNtraver- 
salOn is forced to False. 

Classes 

SeparatorGadget inherits behavior and resources from Object, RectObj, and XmGadget 
Classes. 

The class pointer is xmSeparatorGadgetClass. 
The class name is XmSeparatorGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 



XmSeparatorGadget Resource Set 


Name 


Class 


iyp« 


Default 


Access 


XmN margin 


XmCMargin 


short 


0 


CSG 


XmNorientation 


XmCOrientation 


unsigned char 


XmHORIZONTAL 


CSG 


XmNseparatorType 


XmCSeparatorType 


unsigned char 


XmSHADOW ETCHED IN 


CSG 



XmNmargin 

Specifies the space on the left and right sides between the border of Separator- 
Gadget and the line drawn for horizontal orientation. For vertical orientation, 
specifies the space on the top and bottom between the border of SeparatorGadget 
and the line drawn. 

XmNorientation 

Specifies whether SeparatorGadget is displayed vertically or horizontally. This 
resource can have values of XmVERTICAL and XmHORIZONTAL. 

XmNseparatorType 

Specifies the type of line drawing to be done in the Separator widget. 
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• XmSINGLELINE - single line. 

• XmDOUBLELINE - double line. 

• XmSINGLEDASHEDLINE - single-dashed line. 

• XmDOUBLE_DASHED_LINE - double-dashed line. 

• XmNOLINE - no line. 

• XmSHADOW_ETCHED_IN - double line giving the effect of a line etched into 
the window. The thickness of the double line is equal to the value of XmNsha- 
dowThickness. For horizontal orientation, the top line is drawn in XmNtopSha- 
dowColor and the bottom line is drawn in XmNbottomShadowColor. For verti- 
cal orientation, the left line is drawn in XmNtopShadowCoIor and the right line 
is drawn in XmNbottomShadowColor. 

• XmSHADOW_ETCHED_OUT - double line giving the effect of an etched line 
coming out from the window. The thickness of the double line is equal to the 
value of XmNshadowThickness. For horizontal orientation, the top line is drawn 
in XmNbottomShadowColor and the bottom line is drawn in XmNtopSha- 
dowCoIor. For vertical orientation, the left line is drawn in XmNbottomSha- 
dowColor and the right line is drawn in XmNtopShadowCoIor. 

Inherited Resources 

SeparatorGadget inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 



XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhelpCallback 


XmCCaUback 


XtCallbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightThickness 


XmCHightightThickuess 


short 


0 


CSG 


XmNshadowThickness 


XmCShadowThickness 


short 


2 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddrt 


NULL 


CSG 



RectObj Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


1 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCailback 


XmCCaUback 


XtCallbackList 


NULL 


C 



Keyboard Traversal 

For information on keyboard traversal, see the man page for XmGadget(3X) and its sections 
on behavior and default translations. 
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RELATED INFORMATION 

Object(3X), RectObject(3X), XmCreateSeparatorGadget(3X), and XmGadget(3X). 
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NAME 

XmSetFontUnit - a function that sets the font unit value for a display. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmSetFontUnit (display, font_unit_yalue) 
Display display; 
int font_unit_yakie\ 

DESCRIPTION 

XmSetFontUnit provides an external function to initialize font unit values. Applications may want 
to specify resolution-independent data based on a global font size. This function must be called 
before any widgets with resolution-independent data are created. See the XmNunitType resource 
description in the man pages for XmGadget, XmManager, and XmPrimitive for more information 
on resolution independence. 

display Defines the display for which this font unit value is to be applied. 

font_unit value Specifies the value to be used in the conversion calculations. The font 

unit value is normally taken as the QUAD_WIDTH property of the font; 
however, the application can specify any integer value. 

RELATED INFORMATION 

XmConvertUnits(3X). 
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NAME 

XmSetMenuCursor - a RowColumn function that modifies the menu cursor for a client. 
SYNOPSIS 

void XmSetMenuCursor {display, cursorld) 
Display * display; 

Cursor cursorld; 

DESCRIPTION 

XmSetMenuCursor programmatically modifies the menu cursor for a client; after the cursor has 
been created by the client, this function registers the cursor with the menu system. After calling 
this function, the specified cursor is displayed whenever this client displays an OSF/Motif menu 
on the indicated display. The client can then specify different cursors on different displays. 

display Specifies the display to which the cursor is to be associated. 

cursorld Specifies the X cursor ID. 

For a complete definition of the menu cursor resource, see XmRowColumn(3X). 

RELATED INFORMATION 

XmRowColumn(3X). 
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NAME 

XmSetProtocolHooks - a VendorShell function that allows pre and post actions to be executed 
when a protocol message is received from the window manager. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/ProtocoIs.h> 

void XmSetProtocolHooks {shell, property, protocol, prehook, prejlosure, posthook, 
postjlosure) 

Widget shell; 

Atom property; 

Atom protocol; 

XtCallbackProc prehook} 

caddr_t pre _clo sure; 

XtCallbackProc posthook; 

caddr_t post_closure; 

void XmSetWMProtocolHooks {shell, protocol, prehook, pre_closure, posthook, post_closure) 

Widget shell; 

Atom protocol; 

XtCallbackProc prehook; 

caddr_t prejlosure; 

XtCallbackProc posthook; 

caddr t post closure; 



DESCRIPTION 

XmSetProtocolHooks is used by shells that want to have pre and post actions executed when a 
protocol message is received from the window manager. Since there is no guaranteed ordering in 
execution of event handlers or callback lists, this allows the shell to control the flow while leaving 
the protocol manager structures opaque. 

XmSetWMProtocolHooks is a convenience interface. It calls XmSetProtocolHooks with the pro- 
perty value set to the atom returned by interning WMPROTOCOLS. 



shell Specifies the widget with which the protocol property is associated. 

property Specifies the protocol property. 

protocol Specifies the protocol atom (or an int cast to Atom). 

prehook Specifies the procedure to call before calling entries on the client callback 
list 

prejlosure Specifies the client data to be passed to the prehook when it is invoked. 

posthook Specifies the procedure to call after calling entries on the client callback list. 

postjlosure Specifies the client data to be passed to the posthook when it is invoked. 



For a complete definition of VendorShell and its associated resources, see VendorShell (3X). 



RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmSetWMProtocolHooks (3X) . 
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NAME 



XmSetWMProtocolHooks - a VendorShell convenience interface that allows pre and post actions 
to be executed when a protocol message is received from the window manager. 



SYNOPSIS 

#include <Xm/Xm.h> 
#include <Xll/Protocols.h> 

void XmSetWMProtocolHooks (shell, protocol, prehook, pre_closure, posthook, post_closure) 



Widget 
Atom 

XtCallbackProc 
caddr t 

XtCallbackProc 
caddr t 



sheU; 
protocol^ 
prehook; 
preclosure; 
posthook; 
postclosurc, 



DESCRIPTION 

XmSetWMProtocolHooks is a convenience interface. It calls XmSetProtocolHooks with the pro- 
perty value set to the atom returned by interning WMPROTOCOLS. 

shell Specifies the widget with which the protocol property is associated. 

protocol Specifies the protocol atom (or an int cast to Atom). 

prehook Specifies the procedure to call before calling entries on the client callback 
list. 

pre_closure Specifies the client data to be passed to the prehook when it is invoked. 

posthook Specifies the procedure to call after calling entries on the client callback list. 

post_closure Specifies the client data to be passed to the posthook when it is invoked. 

For a complete definition of VendorShell and its associated resources, see VendorShell(3X). 



RELATED INFORMATION 

VendorShell(3X), XmInternAtom(3X), and XmSetProtocolHooks(3X). 
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NAME 

XmStringBaseline - a compound string function that returns the number of pixels between the 
top of the character box and the baseline of the first line of text. 

SYNOPSIS 

#include <Xm/Xm.h> 

Dimension XmStringBaseline (fontlist, string) 
XmFontList fonttisf, 
XmString string; 

DESCRIPTION 

XmStringBaseline returns the number of pixels between the top of the character box and the base- 
line of the first line of text in the provided compound string. 

fontlist Specifies the font list 

string Specifies the string. 

RETURN VALUE 

Returns the number of pixels between the top of the character box and the baseline of the first 
line of text. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringByteCompare - a compound string function that indicates the results of a byte-by-byte 
comparison. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringByteCompare (57, s2) 
XmString si; 
XmString s2; 

DESCRIPTION 

XmStringByteCompare returns a Boolean indicating the results of a byte-by-byte comparison of 
two compound strings. In some cases, once a compound string is put into a widget, that string is 
converted into an internal form to allow faster processing. Part of the conversion process strips 
out unnecessary or redundant information. If an application then does an XtGetValues to retrieve 
a compound string from a widget (specifically, Label and all of its subclasses), it is not guaranteed 
that the compound string returned will be byte-for-byte the same as the string given to the widget 
originally. 

si Specifies a compound string to be compared with s2. 

s2 Specifies a compound string to be compared with si. 

RETURN VALUE 

Returns True if two compound strings are identical byte-by-byte. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringCompare - a compound string function that compares two strings. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringCompare (si, s2) 



DESCRIPTION 

XmStringCompare returns a Boolean indicating the results of a semantically equivalent com- 
parison of two compound strings. 

Symantically equivalent means that the strings have the same text components, directions, and 
separators. If character sets are specified, they must be equal as well. If either one has a charac- 
ter set of XmSTRING DEFAULT CHARSET, it will match the other character set 

si Specifies a compound string to be compared with s2. 

s2 Specifies a compound string to be compared with si. 

RETURN VALUE 

Returns True if two compound strings are equivalent. 

RELATED INFORMATION 

XmStringCreate(3X). 



XmString 
XmString 



si', 
52; 
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NAME 

XmStringConcat - a compound string function that appends one string to another. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringConcat (si, s2) 



DESCRIPTION 

XmStringConcat appends s2 to the end of si and returns the resulting compound string. The ori- 
ginal strings are preserved. The space for the resulting compound string is allocated within the 
function. After using this function, free this space by calling XmStringFree. 



XmString 
XmString 



si; 
s2; 



si 



s2 



Specifies the compound string to which a copy of s2 is appended. 
Specifies the compound string that is appended to the end of si. 



RETURN VALUE 



Returns a new compound string. 



RELATED INFORMATION 

XmStringCreate(3X) and XmStringFree(3X). 
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NAME 

XmStringCopy - a compound string function that makes a copy of a string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringCopy (si) 



DESCRIPTION 

XmStringCopy makes a copy of a compound string. The space for the resulting compound string 
is allocated within the function. The application is responsible for managing the allocated space. 
The memory can be recovered by calling XmStringFree. 



XmString 



si; 



si 



Specifies the compound string. 



RETURN VALUE 



Returns a new compound string. 



RELATED INFORMATION 

XmStringCreate(3X) and XmStringFree(3X). 
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NAME 

XmStringCreate - a compound string function that creates a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringCreate (text, charset) 
char * text, 

XmStringCharSet charset; 

DESCRIPTION 

XmStringCreate creates a compound string with two components: text and a character set. 
text Specifies a pointer to a null terminated string. 

charset Specifies the character set identifier to be associated with the given text. This can 

be XmSTRING DEFAULT CHARSET. 

RETURN VALUE 

Returns a new compound string. 

RELATED INFORMATION 

XmFontListAdd(3X), XmFontListCreate(3X), XmFontListFree(3X), XmStringBaseline(3X), 
XmStringByteCompare(3X), XmStringCompare(3X), XmStringConcat(3X), XmStringCopy(3X), 
XmStringCreateLtoR(3X), XmStringDirectionCreate(3X), XmStringDraw(3X), 
XmStringDrawImage(3X), XmStringDrawUnderIine(3X), XmStringEmpty(3X), 
XmStringExtent(3X), XmStringFree(3X), XmStringFreeContext(3X), XmStringGetLtoR(3X), 
XmStringGetNextComponent(3X), XmStringGetNextSegment(3X), XmStringHeight(3X), 
XmStringInitContext(3X), XmStringLength(3X), XmStringLineCount(3X), 
XmStringNConcat(3X), XmStringNCopy(3X), XmStringPeekNextComponent(3X), 
XmStringSegmentCreate(3X), XmStringSeparatorCreate(3X), and XmStringWidth(3X). 
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NAME 

XmStringCreateLtoR - a compound string function that creates a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringCreateLtoR (text, charset) 
char * text; 

XmStringCharSet charset; 

DESCRIPTION 

XmStringCreateLtoR creates a compound string with two components: text and a character set. 
This function imposes the semantic of scanning for \n characters in the text When one is found, 
the text up to that point is put into a segment followed by a separator component. No final 
separator component is appended to the end of the compound string. The direction defaults to 
left-to-right. This function assumes that the encoding is single octet rather than double octet per 
character of text. 



text Specifies a pointer to a null terminated string. 

charset Specifies the character set identifier to be associated with the given text. This can 

be XmSTRINGDEFAULTCHARSET. 

RETURN VALUE 

Returns a new compound string. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringDirectionCreate - a compound string function that creates a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringDirectionCreate (direction) 
XmStringDirection direction; 

DESCRIPTION 

XmStringDirectionCreate creates a compound string with a single component, a direction with the 
given value. 

direction Specifies the value of the directional component 

RETURN VALUE 

Returns a new compound string. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 



XmStringDraw - a compound string function that draws a compound string in an X window. 



SYNOPSIS 

#include <Xm/Xm.h> 

void XmStringDraw (4 w, fontlist, string, gc, x, y, width, alignment, layout jlirection, clip) 



Display 
Window 
XmFontList 
XmString 
GC 

Position 

Position 

Dimension 

Byte 

Byte 

XRectangle 



d', 

w, 

fontlist} 

string-, 

gc, 

r> 

width', 
alignment; 
layout Jlirection; 
* clip; 



DESCRIPTION 

XmStringDraw draws a compound string in an X Window. 



d 
w 

fontlist 
string 

gc 
x 

y 

width 
alignment 

layoutjiirection 



clip 



Specifies the display. 

Specifies the window. 

Specifies the font list. 

Specifies the string. 

Specifies the graphics context to use. 

Specifies a coordinate of the rectangle which will contain the displayed 
compound string. 

Specifies a coordinate of the rectangle which will contain the displayed 
compound string. 

Specifies the width of the rectangle which will contain the displayed 
compound string. 

Specifies how the string will be aligned within the specified rectangle. 
It is either XmALIGNMENTBEGINNING, 

XmALIGNMENT CENTER, or XmALIGNMENT END. 

Controls the direction in which the segments of the compound string 
will be laid out. It also determines the meaning of the alignment 
parameter. 

Allows the application to restrict the area into which the compound 
string will be drawn. If NULL, no clipping will be done. 



RELATED INFORMATION 

XmStringCreate(3X). 



Hewlett-Packard Company 



-1- 



Jul 27, 1989 



XmStringDrawImage (3X) 



XmStringDrawImage (3X) 



NAME 



XmStringDrawImage - a compound string function that draws a compound string in an X Win- 
dow and creates an image. 



SYNOPSIS 

#include <Xm/Xm.h> 

void XmStringDrawImage (4 w, fontlist, string, gc, x, y, width, alignment, layout JiirecAon, clip) 



Display 
Window 
XmFontList 
XmString 
GC 

Position 

Position 

Dimension 

Byte 

Byte 

XRectangle 



*d; 
w, 

fontlist, 
string; 
&i 
*> 

r> 

width; 
alignment; 
layout _direction; 
* clip; 



DESCRIPTION 

XmStringDrawImage draws a compound string in an X Window and paints both the foreground 
and background bits of each character. 



d 
w 

fontlist 
string 

gc 
x 

y 

width 
alignment 

layout jlirection 

clip 



Specifies the display. 

Specifies the window. 

Specifies the font list. 

Specifies the string. 

Specifies the graphics context to use. 

Specifies a coordinate of the rectangle which will contain the displayed 
compound string. 

Specifies a coordinate of the rectangle which will contain the displayed 
compound string. 

Specifies the width of the rectangle which will contain the displayed 
compound string. 

Specifies how the string will be aligned within the specified rectangle. 
It is either XmALIGNMENTBEGINNING, 

XmALIGNMENT CENTER, or XmALIGNMENT END. 

Controls the direction in which the segments of the compound string 
will be laid out. It also determines the meaning of the alignment 
parameter. 

Allows the application to restrict the area into which the compound 
string will be drawn. If NULL, no clipping will be done. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringDrawUnderline - a compound string function that underlines a string drawn in an X 
Window. 



SYNOPSIS 

#include <Xm/Xmuh> 

void XmStringDrawUnderline (d, w, fontlist, string gc, x, y, width, alignment, layoutJUrection, 
clip, 



underline) 



Display 

Window 

XmFontList 

XmString 

GC 

Position 

Position 

Dimension 

Byte 

Byte 

XRectangle 
XmString 



*d; 
w, 

fontlist; 
string} 
gc, 
x; 

y> 

width; 
alignment; 
layout jiirection; 
* clip; 
underline; 



DESCRIPTION 

XmStringDrawUnderline draws a compound string in an X Window. If the substring identified by 
underline can be matched in string, the substring will be underlined. Once a match has occurred, 
no further matches or underlining will be done. 

d Specifies the display. 

w Specifies the window. 

fontlist Specifies the font list. 

string Specifies the string. 

gc Specifies the graphics context to use. 

x Specifies a coordinate of the rectangle which will contain the displayed 

compound string. 

y Specifies a coordinate of the rectangle which will contain the displayed 

compound string. 

width Specifies the width of the rectangle which will contain the displayed 

compound string. 

alignment Specifies how the string will be aligned within the specified rectangle. 

It is either XmALIGNMENTBEGINNING, 

XmALIGNMENTCENTER, or XmALIGNMENTEND. 

layoutJUrection Controls the direction in which the segments of the compound string 

will be laid out. It also determines the meaning of the alignment 
parameter. 

clip Allows the application to restrict the area into which the compound 

string will be drawn. If NULL, no clipping will be done. 

underline Specifies the substring to be underlined. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringEmpty - a compound string function that provides information on the existence of 
non-zero length text components. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringEmpty (si) 

XmString si; 

DESCRIPTION 

XmStringEmpty returns a Boolean indicating whether or not any non-zero length text components 
exist in the provided compound string. It returns True if there are no text segments in the string. 
If this routine is passed NULL as the string, it returns True. 

si Specifies the compound string. 

RETURN VALUE 

Returns True if there are no text segments in the string. If this routine is passed NULL as the 
string, it returns True. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringExtent - a compound string function that determines the size of the smallest rectangle 
that will enclose the compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmStringExtent {fontlist, string width, height) 
XmFontList fontlist} 
XmString string; 
Dimension width; 
Dimension height; 

DESCRIPTION 

XmStringExtent determines the width and height, in pixels, of the smallest rectangle that will 
enclose the provided compound string. 

fontlist Specifies the font list 

string Specifies the string. 

width Specifies the width of the rectangle. 

height Specifies the height of the rectangle. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringFree - a compound string function that recovers memory. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmStringFree (string) 



DESCRIPTION 

XmStringFree recovers memory used by a compound string. 



XmString 



string-, 



string 



Specifies the compound string to be freed. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringFreeContext - a compound string function that instructs the toolkit that the context is 
no longer needed. 

SYNOPSIS 

#include <Xm/Xm.h> 

void XmStringFreeContext (context) 

XmStringContext * context; 

DESCRIPTION 

XmStringFreeContext instructs the toolkit that the context is no longer needed and will not be 
used without reinitialization. 

context Specifies the string context structure which was allocated by the XmStringlnitCon- 

text function. 

RELATED INFORMATION 

XmStringCreate(3X) and XmStringInitContext(3X). 
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NAME 

XmStringGetLtoR - a compound string function that searches for a text segment in the input 
compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringGetLtoR (string, charset, text) 
XmString string, 
XmStringCharSet charset; 
char ** text, 

DESCRIPTION 

XmStringGetLtoR searches for a text segment in the input compound string that matches the 
given character set identifier. 

string Specifies the compound string. 

charset Specifies the character set identifier to be associated with the text This can be 

XmSTRING DEFAULT CHARSET. 

text Specifies a pointer to a null terminated string. 

RETURN VALUE 

Returns True if the matching text segment can be found. On return, text will have a null ter- 
minated octet sequence containing the matched segment. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringGetNextComponent - a compound string function that returns the type and value of the 
next component in a compound string. 



SYNOPSIS 

#include <Xm/Xm.h> 

XmStringComponentlype XmStringGetNextComponent [context, text, charset, direction, 

unknown Jag unknown Jength, unknown value) 
XmStringContext * context, 

char ** text, 

XmStringCharSet * charset; 

XmStringDirection * direction', 

XmStringComponentlype * unknown jag; 

short * unknown Jength; 

char ** unknown value; 



DESCRIPTION 

XmStringGetNextComponent returns the type and value of the next component in the compound 
string identified by context. It is a low-level component function. Components are returned one at 
a time. On return, only some output parameters will be valid; which ones can be determined by 
examining the return status. In the case of text, charset or direction components, only one output 
parameter is valid. If the return status indicates an unknown component was encountered, the tag, 
length, and value are returned. This function allocates the space necessary to hold returned 
values; freeing this space is the caller's responsibility. 



context 



text 

charset 



direction 
unknown jag 
unknown Jength 
unknown value 



Specifies the string context structure which was allocated by the 
XmStringlnitContext function. 

Specifies a pointer to a null terminated string. 

Specifies the character set identifier to be associated with the text. This 
can be XmSTRING DEFAULT CHARSET. 

Specifies the direction of the text. 

Specifies the tag of an unknown component. 

Specifies the length of an unknown component. 

Specifies the value of an unknown component. 



RETURN VALUE 

Returns the type of component found. 



RELATED INFORMATION 

XmStringCreate(3X) and XmStringInitContext(3X). 
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NAME 

XmStringGetNextSegment - a compound string function that fetches the octets in the next seg- 
ment of a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringGetNextSegment (context, text, charset, direction, separator) 
XmStringContext * context} 

char ** text; 

XmStringCharSet * charset; 

XmStringDirection * direction; 

Boolean * separator, 

DESCRIPTION 

XmStringGetNextSegment fetches the octets in the next segment; repeated calls fetch sequential 
segments. The text, charset, and direction of the fetched segment are returned each time. A 
Boolean status is returned to indicate whether a valid segment was successfully parsed. 

context Specifies the string context structure which was allocated by the 

XmStringlnitContext function. 

text Specifies a pointer to a null terminated string. 

charset Specifies the character set identifier to be associated with the text. This 

can be XmSTRING DEFAULT CHARSET. 

direction Specifies the direction of the text. 

separator Specifies if the next component of the compound string is a separator. 



RETURN VALUE 

Returns True if a valid segment is found. 

RELATED INFORMATION 

XmStringCreate(3X) and XmStringInitContext(3X). 
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NAME 

XmStringHeight - a compound string function that returns the line height of the given compound 
string. 

SYNOPSIS 

#include <Xm/Xm.h> 

Dimension XmStringHeight (fontlist, string) 
XmFontList fontlist; 
XmString string", 

DESCRIPTION 

XmStringHeight returns the height, in pixels, of the sum of all the line heights of the given com- 
pound string. Separator components delimit lines. 

fontlist Specifies the font list. 

string Specifies the string. 

RETURN VALUE 

Returns the height of the specified string. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringlnitContext - a compound string function that allows applications to read out the con- 
tent segment by segment. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmStringlnitContext {context, string) 
XmStringContext * context, 

XmString string; 

DESCRIPTION 

XmStringlnitContext maintains a context to allow applications to read out the contents of a com- 
pound string segment by segment This function establishes the context for this read out. This 
context is used when reading subsequent segments out of the string. A Boolean status is returned 
to indicate if the input string was able to be parsed. 

context Specifies a pointer to the allocated context. 

string Specifies the string. 

RETURN VALUE 

Returns True if the context was allocated. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringLength - a compound string function that obtains the length of a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

int XmStringLength (si) 



DESCRIPTION 

XmStringLength obtains the length of a compound string. It returns the number of bytes in si 
including all tags, direction indicators, and separators. If the compound string has an invalid 
structure, zero is returned. 



XmString 



si; 



si 



Specifies the compound string. 



RETURN VALUE 



Returns the length of the compound string. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringLineCount - a compound string function that returns the number of separators plus 
one in the provided compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

int XmStringLineCount (string) 

XmString string} 

DESCRIPTION 

XmStringLineCount returns the number of separators plus one in the provided compound string. 
In effect, it counts the number of lines of text. 

string Specifies the string. 

RETURN VALUE 

Returns the number of lines in the compound string. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringNConcat - a compound string function that appends a specified number of bytes to a 
compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringNConcat (si, s2, num_bytes) 
XmString si; 
XmString s2; 
int num_bytes; 

DESCRIPTION 

XmStringNConcat appends a specified number of bytes from s2 to the end of si, including tags, 
directional indicators, and separators. It then returns the resulting compound string. The original 
strings are preserved. The space for the resulting compound string is allocated within the func- 
tion. The application is responsible for managing the allocated space. The memory can be 
recovered by calling XmStringFree. 

si Specifies the compound string to which a copy of s2 is appended. 

s2 Specifies the compound string that is appended to the end of si. 

numjyytes Specifies the number of bytes of s2 to append to si. If this value is less than the 
length of s2, the resulting string will not be a valid compound string. 

RETURN VALUE 

Returns a new compound string. 

RELATED INFORMATION 

XmStringCreate(3X) and XmStringFree(3X). 
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NAME 

XmStringNCopy - a compound string function that creates a copy of a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringNCopy (si, man bytes) 
XmString sl\ 
int numjbytes; 

DESCRIPTION 

XmStringNCopy creates a copy of si which contains a specified number of bytes, including tags, 
directional indicators, and separators. It then returns the resulting compound string. The original 
strings are preserved. The space for the resulting compound string is allocated within the func- 
tion. The application is responsible for managing the allocated space. The memory can be 
recovered by calling XmStringFree. 

si Specifies the compound string. 

num bytes Specifies the number of bytes of si to copy. If this value is less than the length of 
si, the resulting string will not be a valid compound string. 

RETURN VALUE 

Returns a new compound string. 

RELATED INFORMATION 

XmStringCreate(3X) and XmString¥ree(3X). 
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NAME 

XmStringPeekNextComponent - a compound string function that returns the component type of 
the next component fetched. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmStringComponentType XmStringPeekNextComponent (context) 
XmStringContext * context; 

DESCRIPTION 

XmStringPeekNextComponent examines the next component which would be fetched by 
XmStringGetNextComponent and returns the component type. 

context Specifies the string context structure which was allocated by the XmStringlnitCon- 

text function. 

RETURN VALUE 

Returns the type of component found. 

RELATED INFORMATION 

XmStringCreate(3X) and XmStringInitContext(3X). 
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NAME 

XmStringSegmentCreate - a compound string function that creates a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringSegmentCreate (text, charset, direction, separator) 

char * text, 

XmStringCharSet charset; 

XmStringDirection direction; 

Boolean separator; 



DESCRIPTION 

XmStringSegmentCreate is a high-level function which assembles a compound string consisting of 
a character set identifier, a direction component, a text component, and an optional separator 
component. 



text Specifies a pointer to a null terminated string. 

charset Specifies the character set identifier to be associated with the text. This can be 

XmSTRINGDEFAULTCHARSET. 

direction Specifies the direction of the text. 

separator Specifies separator addition. If False, the compound string will not have a separa- 
tor at the end. If True, a separator will immediately follow the text component. 



RETURN VALUE 

Returns a new compound string. 



RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringSeparatorCreate - a compound string function that creates a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

XmString XmStringSeparatorCreate () 



DESCRIPTION 

XmStringSeparatorCreate creates a compound string with a single component, a separator. 

RETURN VALUE 

Returns a new compound string. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmStringWidth - a compound string function that returns the width of the longest sequence of 
text components in a compound string. 

SYNOPSIS 

#include <Xm/Xm.h> 

Dimension XmStringWidth {fontlist, string) 
XmFontList fontlist; 
XmString string; 

DESCRIPTION 

XmStringWidth returns the width, in pixels, of the longest sequence of text components in the 
provided compound string. Separator components are used to delimit sequences of text com- 
ponents. 

fontlist Specifies the font list 

string Specifies the string. 

RETURN VALUE 

Returns the width of the compound string. 

RELATED INFORMATION 

XmStringCreate(3X). 
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NAME 

XmText - the Text widget class. 

SYNOPSIS 

#include <Xm/Text.h> 

DESCRIPTION 

Text provides a single and multiline text editor for customizing both user and programmatic inter- 
faces. It can be used for single-line string entry, forms entry with verification procedures, and 
full-window editing. It provides an application with a consistent editing system for textual data. 
The screen's textual data adjusts to the application writer's needs. 

Text provides separate callback lists to verify movement of the insert cursor, modification of the 
text, and changes in input focus. Each of these callbacks provides the verification function with 
the widget instance, the event that caused the callback, and a data structure specific to the 
verification type. From this information the function can verify if the application considers this to 
be a legitimate state change and can signal the widget whether to continue with the action. 

The user interface tailors a new set of translations. The default translations provide key bindings 
for insert cursor movement, deletion, insertion, and selection of text. 

Text allows the user to select regions of text Selection is based on the Interclient Communication 
Conventions (1CCC) selection model. Text supports both primary and secondary selection. 

Primitive's resource XmNtraversalOn is always True in Text. 

The Text widget includes native-language support. This makes it possible for the programmer to 
edit text in a preferred language. 

Classes 

Text inherits behavior and resources from Core and Primitive classes. 
The class pointer is xmTextWidgetClass. 
The class name is XmText. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGet Values (G), or is not applicable (N/A). 
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XmText Resource Set 


Name 


Class 


Type 


Default 


Access 


XrnNactivateCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNautoSbcwCursorFosition 


XmCAutoShowCursorPosition 


Boolean 


True 


CSG 


XmNcursorPosition 


XmCCursorPosition 


XmTextPosition 


0 


CSG 


XmNeditable 


XmCEditable 


Boolean 


True 


CSG 


XmNeditMode 


XmCEditMode 


int 


XmSINGLE_LINE_EDlT 


CSG 


XmNfocusCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNlosingFocusCallback 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmarginHeight 


XmCMarginHeight 


short 


3 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


3 


CSG 


XmNmaxLength 


XmCMaxLength 


int 


MAXINT 


CSG 


XmNmodifyVerifyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNmotionVerifyCallbadi 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNtopPosition 


XmCTcxtPosition 


XmTextPosition 


0 


CSG 


XmNvalue 


XmCValue 


String 




CSG 


XmNvalueChangedCallback 


XmCCallback 


XtCallbackList 


NULL 


C 



XmNactivateCallback 

Specifies the list of callbacks that is called when the user invokes an event that calls 
the Activate() function. The structure returned by this callback is XmAnyCallback- 
Struct. The reason sent by the callback is XmCR_ACnVATE. 

XmNautoShowCursorPosition 

Ensures that the visible text contains the insert cursor when set to True. If the 
insert cursor changes, the contents of Text may scroll in order to bring the insertion 
point into the window. 

XmNcursorPosition 

Indicates the position in the text where the current insert cursor is to be located. 
Position is determined by the number of characters from the beginning of the text. 

XmNeditable 

Indicates that the user can edit the text string when set to True. A false value will 
prohibit the user from editing the text. 

XmNeditMode 

Specifies the set of keyboard bindings used in Text. The default keyboard bindings 
(XmSINGLE_LINE EDIT) provides the set of key bindings to be used in editing 
single-line text. The~multiline bindings (XmMULTI_LINE_EDrT) provides the set 
of key bindings to be used in editing multiline text. 

XmNfocusCallback 

Specifies the list of callbacks that is called before Text has accepted input focus. 
The structure returned by this callback is XmAnyCallbackStruct. The reason sent 
by the callback is XmCR_FOCUS. 

XmNlosingFocusCallback 

Specifies the list of callbacks that is called before Text loses input focus. The struc- 
ture returned by this callback is XmTextVerifyCallbackStruct. The reason sent by 
the callback is XmCR LOSING FOCUS. 

XmNmarginHeight 

Specifies the distance between the top edge of the widget window and the text, and 
the bottom edge of the widget window and the text. This resource is forced to True 
when the Text widget is placed in a ScrolledWindow with XmNscrollingPoIicy set to 
XmAUTOMATIC. 

XmNmarginWidth 

Specifies the distance between the left edge of the widget window and the text, and 
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the right edge of the widget window and the text. This resource is forced to True 
when the Text widget is placed in a ScrolledWindow with XmNscrollingPolicy set to 
XmAUTOMATIC. 

XmNmaxLength 

Specifies the maximum length of the text string that can be entered into text from 
the keyboard. Strings that are entered using the XmNvalue resource or the 
XmTextSetString function ignore this resource. 

XmNmodifyVerifyCallback 

Specifies the list of callbacks that is called before text is deleted from or inserted 
into Text. The structure returned by this callback is XmTextVerifyCallbackStract. 
The reason sent by the callback is XmCR_MODIFYING_TEXT_VALUE. 

XmNmotionVerifyCallback 

Specifies the list of callbacks that is called before the insert cursor is moved to a 
new position. The structure returned by this callback is XmTextVerifyCallback- 
Struct. The reason sent by the callback is XmCR MOVING INSERT CURSOR. 

XmNtopPosition 

Displays the position of text at the top of the window. Position is determined by the 
number of characters from the beginning of the text. 

XmNvalue 

Displays the string value. XtGetValues returns the value of the internal buffer and 
XtSet Values copies the string values into the internal buffer. 

XmNvalueChangedCallback 

Specifies the list of callbacks that is called after text is deleted from or inserted into 
Text. The structure returned by this callback is XmAnyCallbackStmct. The reason 
sent by the callback is XmCRVALUECHANGED. 



XmText Input Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNpendingDelete 


XmCPendingDelete 


Boolean 


True 


CSG 


XmNsclectionArray 


XmCSelectionArray 


Pointer 


sarray 


CSG 


XmNselectThreshold 


XmCSelectThreshold 


int 


5 


CSG 



XmNpendingDelete 

Indicates that pending delete mode is on when the Boolean is True. Pending dele- 
tion is defined as deletion of the selected text when an insertion is made. 

XmNselectionArray 

Defines the actions for multiple-mouse clicks. Each mouse click performed within a 
half of a second of the previous mouse click will increment the index into this array 
and perform the defined action for that index. The possible actions are: 

• XmSELECT_POSITIONS - resets the insert cursor position. 

• XmSELECT WORD - selects a word. 

• XmSELECT_LINE - selects a line of text. 

• XmSELECT ALL - selects all of the text. 
XmNselectThreshold 

Specifies the number of pixels of motion that is required to select the next character 
when selection is performed using the click-drag mode of selection. 
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XmText Output Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNblinkRate 


XmCBlinkRate 


vat 


500 


CSG 


XmNcolumns 


XmCColumns 


short 


20 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


fixed 


CSG 


XmNcureorPositionVisible 


XmCCursorPositkmVisible 


Boolean 


True 


CSG 


XmNresizeHeight 


XmCResizeHeight 


Boolean 


False 


CSG 


XmNresizeWidth 


XroCResize Width 


Boolean 


False 


CSG 


XmNrows 


XmCRows 


short 


1 


CSG 


XmNwordWrap 


XmCWordWrap 


Boolean 


False 


CSG 



XmNblinkRate 

Specifies the blink rate of the text cursor in milliseconds. The time indicated in the 
blink rate relates to the length of time the cursor is visible and the time the cursor is 
invisible (i.e., the time it will take to blink the insertion cursor on and off will be 2 
times the blink rate). The cursor will not blink when the blink rate is set to zero. 

XmNcolumns 

Specifies the initial width of the text window measured in character spaces. 
XmNfontList 

Specifies the font list to be used for Text. See XmFontListCreate(3X) to create a 
font list. 

XmNinsertionPointVisible 

Indicates that the insert cursor position is marked by a blinking text cursor when the 
Boolean is True. 

XmNresizeHeight 

Indicates that Text will attempt to resize its height to accommodate all the text con- 
tained in the widget when Boolean is True. If set to True, the text will always be 
displayed starting from the first position in the source, even if instructed otherwise. 
This attribute is ignored when using a ScrolledText widget and when 
XmNscroIlVertical is True. 

XmNresizeWidth 

Indicates that Text will attempt to resize its width to accommodate all the text con- 
tained in the widget when Boolean is True. This attribute is ignored if 
XmNwordWrap is True. 

XmNrows 

Specifies the initial height of the text window measured in character heights. This 
attribute is ignored if the text widget resource XmNeditMode is 
XmSINGLELINEEDIT. 

XmNwordWrap 

Indicates that lines are to be broken at word breaks (i.e., the text does not go off the 
right edge of the window) when Boolean is True. Words are defined as a sequence 
of characters separated by white space. White space is defined as a space, tab, or 
newline. This attribute is ignored if the text widget resource XmNeditMode is 
XmSINGLELINEEDIT. 

The following resources are only used when text is created in a ScrolledWindow. See the 
man page for XmCreateScrolledTexL 
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XmText ScrolkdText Resource Set 


Name 


Class 




Default 


Access 


XmNscrollHorizontal 


XmCScroU 


Boolean 


True 


CG 


XmNscrollLeftSide 


XmCScrollSide 


Boolean 


False 


CG 


XmNscrollTopSide 


XmCScrollSide 


Boolean 


False 


CG 


XmNscrollVertical 


XmCScroU 


Boolean 


True 


CG 



XmNscrollHorizontal 

Adds a ScrollBar that allows the user to scroll horizontally through text when 
Boolean is True. This attribute is ignored if the Text resource XmNeditMode is 
XmSINGLELINE EDIT. This resource is forced to False when the Text widget is 
placed in a ScrolledWindowwith XmNscroIIingPolicy set to XmAUTOMATIC. 

XmNscrollLeftSide 

Indicates that the vertical ScrollBar should be placed on the left side of the scrolled 
text window when Boolean is True. This attribute is ignored if XmNscrollVertical is 
False or the Text resource XmNeditMode is XmSINGLELINEEDTT. 

XmNscrollTopSide 

Indicates that the horizontal ScrollBar should be placed on the top side of the 
scrolled text window when Boolean is True. 

XmNscrollVertical 

Adds a ScrollBar that allows the user to scroll vertically through text when Boolean 
is True. This resource is forced to False when the Text widget is placed in a Scrol- 
ledWindow with XmNscroIIingPolicy set to XmAUTOMATIC. 

Inherited Resources 

Text inherits behavior and resources from the following superclasses. For a complete 
description of these resources, refer to the man page for that superclass. 



Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottomShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmN foreground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCaUback 


XmCCallbadc 


XtCallbackList 


NULL 


CSG 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


XmNhighlightPixmap 


XmCHighlightPixmap 


Pixmap 


dynamic 


CSG 


XmNhighlighrTbickness 


XmCHighlightTbickness 


short 


0 


CSG 


XmNsbadoWThickness 


XmCShadcwThidcncss 


short 


2 


CSG 


XmNtopShadcwColor 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNtopShadowPixmap 


XmCTopShadowPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


True 


N/A 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 
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Core Resource Set 


Name 


Class 


Type 


Default 


Access 


- XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbadcground 


XmCBackground 


Pixel 


dynamic 


CSG 


XmNbadcgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallbadc 


XmCCallback 


XtCallbackList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWheriManaged 


XrnCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmN width 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback. 

typedef struct 

{ 

int 

XEvent 
} XmAnyCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 



reason; 
* event; 



The Text widget defines a new callback structure for use with verification callbacks. Note 
that not all of the fields are relevant for every callback reason. The application must first 
look at the reason field and use only the structure members that are valid for the particular 
reason. The following structure is returned with XmNlosingFocusCallbacks, XmNmo- 
difyVerifyCallbacks, and XmNmotionVerifyCallbacks. 



typedef struct 

{ 

int reason; 

XEvent * event; 

Boolean doit; 

XmTextPosition currlnsert, newlnsert; 

XmTextPosition startPos, endPos; 

XmTextBlock text; 
} XmTextVerifyCallbackStruct, *XmTextVerifyPtr; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 
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doit Indicates whether that action that invoked the callback will be performed. 

Setting doit to False negates the action. 

currlnsert Indicates the current position of the insert cursor. 

newlnsert Indicates the position at which the user attempts to position the insert cur- 



startPos Indicates the starting position of the text to modify. If the callback is not a 

modify verification callback, this value is the same as currlnsert. 

endPos Indicates the ending position of the text to modify. If no text is replaced or 

deleted, then the value is the same as startPos. If the callback is not a 
modify verification callback, this value is the same as currlnsert. 

text Points to a structure of type XmTextBlockRec. This structure holds the tex- 

tual information to be inserted. 



typedef struct 

{ 

char *ptr, 
int length; 
XmTextFormat format; 
} XmTextBlockRec, *XmTextBlock; 

ptr Points to the text to be inserted. 

lengfh Specifies the length of the text to be inserted. 

format Specifies the format of the text (e.g., FMT8BIT). 

The following table describes the reasons for which the individual verification callback struc- 
ture fields are valid: 



Reason 


Valid Fields 


XmCRLOSINGFOCUS 

XmCR MODIFYING TEXT VALUE 

XmCR MOVING TEXT CURSOR 


reason, event, doit, currlnsert, 
newlnsert, startPos, endPos 

reason, event, doit, currlnsert, 
newlnsert, startPos, endPos, text 

reason, event, doit, currlnsert, 
newlnsert 



Behavior 

The behavior for the Text widget is determined by the XmNeditMode resource. Depending 
on how this resource is set, some of the key bindings will perform different actions. The 
possible values for XmNeditMode are XmSINGLE_LINE_EDIT and 
XmMULTI LINE EDIT. The following describes the key bindings for these edit modes. 



Default Behavior (Single-line Text Edit) 
<BtnlDown>: 

This key binding performs the action defined in the selection array depending on 
the number of multiple mouse clicks. The default selection array ordering is one 
click to move the insertion cursor position, two clicks to select a word, and three 
clicks to select a line of text. 

It also begins text selection. Primary selected text that was previously selected 
becomes unselected. 
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Buttonl <PtrMoved>: 

Text is selected in the direction of the pointer cursor movement. While the pointer 
cursor is moved along the text, the text is selected from the point the mouse button 
1 was pressed to the present position of the pointer cursor. Moving the pointer cur- 
sor back over previously selected text while mouse button 1 is pressed deselects the 
text. Primary selected text is shown visibly by inverted text. 

<BtnlUp>: 

The selected text becomes the primary selection (i.e., the selection is committed). 
Shift <BtnlDown>: 

The end points of the selection move to the point where the pointer cursor is 
located when the shifted mouse button 1 is pressed. If the pointer cursor is located 
at a position where text is already selected, the text following this position becomes 
unselected. 

<Btn2Down>: 

Begins secondary selection of text 

Button2 <PtrMoved>: 

The text is selected much the same way as when mouse button 1 is dragged, except 
the selected text becomes the secondary selection. This is shown visibly by under- 
lined text. 

<Btn2Up>: 

The text is copied from the secondary selection to the insertion point located at the 
insert cursor. This is shown visibly by underlined text. If no secondary selection, 
primary selection is copied. 

CTRL <Btn2Up>: 

The text is copied and cut from the secondary selection and is pasted to the inser- 
tion point located at the insert cursor. If no secondary selection, primary selection 
is copied and cut. 

Shift < Key > Up: 

The text beginning with the character above the insert cursor is selected and 
displayed in inverse video (i.e., primary selection) from that point to the insert cur- 
sor. If there is already selected text above the insert cursor, this text becomes 
unselected. 

Shift<Key>Down: 

The text beginning with the character below the insert cursor is selected and 
displayed in inverse video (i.e., primary selection) from that point to the insert cur- 
sor. If there is already selected text below the insert cursor, this text becomes 
unselected. 

<Key> Right: 

The insert cursor moves one character to the right. 

Shift <Key> Right: 

The text character to the right of the insert cursor is selected and inverted (i.e., pri- 
mary selection). If there is already selected text to the right of the insert cursor, this 
text becomes unselected one character at a time. 

CTRL <Key> Right: 

The insert cursor moves to the end of the line. 

<Key> Left: 

The insert cursor moves one character to the left 

Shift <Key> Left: 

The text character to the left of the insert cursor is selected and inverted. If there is 
already selected text to the left of the insert cursor, this text becomes unselected one 
character at a time. 
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CTRL <Key> Left: 

The insert cursor moves to the beginning of the line. 

<Key> Backspace: 

The character of text immediately preceding the insert cursor is deleted. 

<K«y> Delete or <Key>DeleteChar (HP keyboard): 

The character of text immediately following the insert cursor is deleted. 

Any <Key>: 

This key binding inserts the character, associated with the key pressed, into the text 
of the Text widget. 

<Key> Return- 
Calls the callbacks for XmNactivateCallback. 

Multiline Text Edit 

Buttonl <PtrMoved>: 

Text is selected in the direction of the pointer cursor movement While the pointer 
cursor is moved along the text, the text is selected from the point that mouse button 
1 was pressed to the present position of the pointer cursor. Moving the cursor over 
several lines selects text to the end of each line passed over and up to the position of 
the pointer cursor on the current line. Moving the pointer cursor back over previ- 
ously selected text while mouse button 1 is pressed deselects the text. 

<Key> Up : 

The insert cursor moves to the line directly above the current line where the insert 
cursor is residing. 

<Key> Down: 

The insert cursor moves to the line directly below the current line where the insert 
cursor is residing. 

<Key> Return: 

Inserts a new line at the point where the insert cursor is positioned. 

Default Translations 

Default translations for Text are: 



Shift < Key >Tab: 
<Key>Tab: 
CtrK Key >Tab: 
<Key>Up: 

< Key > Down: 

< Key > Home: 
CtrK Key > Right: 
Shift < Key > Right: 
<Key>Right: 
CtrK Key > Left: 
Shift <Key>Left: 
<Key>Left: 

Shift < Key > Backspace: 
<Key>BackSpace: 
<Key>Return: 
<Key>: 

Shift <BtnlDown>: 
<BtnlDown>: 
Buttonl <PtrMoved>: 
<BtnlUp>: 
<Btn2Down>: 



prev-tab-group() 

next-tab-group() 

next-tab-group() 

traverse-prev() 

traverse-next () 

traverse-home() 

forward-word() 

key-select(right) 

forward-characterQ 

backward-word() 

key-select (left) 

backward -character() 

delete-previous-word() 

deIete-previous-character() 

activate() 

self-insert () 

extend -start () 

grab-focus() 

extend -adjust() 

extend -end () 

secondary-start () 
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Button2<PtrMoved>: secondary-adjust () 

Ctrl<Btn2Up>: move-to() secondary-end-and-kill() 

<Btn2Up>: copy-to() secondary-end() 

< Client Message >: secondary-stuff() remote-kill-selection() 
<LeaveWindow>: leave() 

<FocusIn>: focusln() 

< FocusOut > : focusOut () 
<Unmap>: unmap() 



If using an HP keyboard, the following are the default translations: 

Shift<Key>DeleteChan delete-next-word() 
<Key>DeIeteChan delete-next-character () 

If using a DIGITAL keyboard, the following are the default translations: 

Shift < Key > Delete: delete-previous-word() 

< Key > Delete: delete-previous-character () 
Shift < Key > Linefeed: delete-next-word() 

< Key > Linefeed: delete-next -character () 
Shift <Key>F13: delete-next ^word() 
<Key>F13: delete-next -character() 

If using other than an HP or DIGITAL keyboard, the following are the default translations: 

Shift < Key > Delete: delete-next -word () 

< Key > Delete: delete-next -character() 



The following default translations override the above default translations when using Multi- 
line Text Edit: 

<Key>Tab: self-insert() 

< Key > Up: previous-line() 

< Key > Down: next-Iine() 

< Key > Home: beginning-of-file() 

< Key > Return: newlineQ 



When changing from Multiline Text Edit to Single-line Text Edit, the following default trans- 
lations override the Multiline Text Edit default translations. 



'Shift 'Ctrl 'Meta<Key>Tab: next-tab-group() 
<Key>Up: traverse-prev() 

< Key > Down: traverse-next() 

< Key > Home: traverse-home() 

< Key > Return: activate() 

Keyboard Traversal 

Multiline Text Edit differs from standard traversal in the following manner: 
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Up or Down Arrow - moves the insert cursor between lines. 
Tab - inserts a tab. 

Home - moves the insert cursor to the first position (top) of the file. 
Return - adds a new line. 

Both Single-line and Multiline Text Edit differs from standard traversal in the fol- 
lowing manner: 

Right or Left Arrows - moves the insert cursor to the right or to the left. 

For more information on keyboard traversal, see the man page for XmPrimitive(3X) and its 
sections on behavior and default translations. 

Native-Language Support 

The Text widget supports editing of both American/European (8-bit) and Asian (16-bit) 
characters. To view and edit 16-bit characters, the appropriate font must be loaded via 
XmNfontList and 16-bit text must be encoded in HP-15. 

The Text widget is a character-based editor, for which the character is the minimum object. 
The cursor is always located at the character position instead of at the internal byte position 
and is reflected by the XmTextPosition resource. 

Word definition is extended for 16-bit text. In addition to the white space, the Text widget 
recognizes the word boundary between 8- and 16-bit characters. 

The Text widget supports 24 language versions of the HP keyboard for character entry. 
KBD_LANG is an environment variable that specifies the keyboard language. Valid names 
of the keyboard languages are names with KB_ removed from those language names in 
/usr/include/Xll/XHPlib.h. If KBD LANG is not set or is set to an invalid value, then the 
Text widget determines the language of the physical keyboard in use and uses that language 
for the character entry. It is not possible for one client to have more than one keyboard 
language; and, switching the keyboard language dynamically is not supported. 

The NLIO subsystem is necessary for Asian character use. 

RELATED INFORMATION 

Core(3X), XmCreateScroUedText(3X), XmCreateText(3X), XmFontListCreate(3X), 
XmPrimitive(3X), XmTextClearSelection(3X), XmTextGetEditable(3X), 

XmTextGetMaxLength(3X), XmTextGet Select ion(3X), XmTextGetString(3X), XmTextReplace(3X), 
XmTextSetEditable(3X), XmTextSetMaxLength(3X), XmTextSetSeiection(3X), and 
XmTextSetString(3X). 
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NAME 

XmTextClearSelection - a Text function that clears the primary selection. 

SYNOPSIS 

#include <Xm/Text.h> 

void XmTextClearSelection (widget, time) 
Widget widget; 
Time time; 

DESCRIPTION 

XmTextClearSelection clears the primary selection in the Text widget; it has no effect on the text 
that was previously selected. 

widget Specifies the Text widget ID. 

time Specifies the time at which the selection value is desired. This should be the time 

of the event which triggered this request 

For a complete definition of Text and its associated resources, see XmText(3X). 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextGetEditable - a Text function that accesses the edit permission state. 

SYNOPSIS 

#include <Xm/Text.h> 

Boolean XmTextGetEditable (widget) 
Widget widget; 

DESCRIPTION 

XmTextGetEditable accesses the edit permission state of the Text widget 
widget Specifies the Text widget ID. 

For a complete definition of Text and its associated resources, see XmText(3X). 
RETURN VALUE 

Returns a Boolean value that indicates the state of the XmNeditable resource. 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextGetMaxLength - a Text function that accesses the value of the current maximum allow- 
able length of a text string entered from the keyboard. 

SYNOPSIS 

#include <Xm/Text.h> 

int XmTextGetMaxLength (widget) 

Widget widget; 

DESCRIPTION 

XmTextGetMaxLength accesses the value of the current maximum allowable length of the text 
string in the Text widget entered from the keyboard. The maximum allowable length prevents the 
user from entering a text string larger than this limit 

widget Specifies the Text widget ID. 

For a complete definition of Text and its associated resources, see XmText(3X). 
RETURN VALUE 

Returns the integer value that indicates the string's maximum allowable length that can be entered 
from the keyboard. 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextGetSekction - a Text function that retrieves the value of the primary selection. 



SYNOPSIS 

#include <Xm/Text.h> 

char * XmText Get Selection (widget) 
Widget widget; 



DESCRIPTION 

XmTextGetSelection retrieves the value of the primary selection. It returns a NULL pointer if no 
text is selected in the widget. The application is responsible for freeing the storage associated with 
the string by calling XtFree. 

widget Specifies the Text widget ID. 

For a complete definition of Text and its associated resources, see XmText(3X). 
RETURN VALUE 

Returns a character pointer to the string that is associated with the primary selection. 



RELATED INFORMATION 
XmText (3X). 
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NAME 

XmTextGetString - a Text function that accesses the string value. 

SYNOPSIS 

#include <Xm/Text.h> 

char * XmTextGetString (widget) 

Widget widget; 

DESCRIPTION 

XmTextGetString accesses the string value of the Text widget. The application is responsible for 
freeing the storage associated with the string by calling XtFree. 

widget Specifies the Text widget ID. 

For a complete definition of Text and its associated resources, see XmText(3X). 
RETURN VALUE 

Returns a character pointer to the string value of the text widget 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextReplace - a Text function that replaces part of a text string. 

SYNOPSIS 

#include <Xm/Text.h> 

void XmTextReplace (widget, from j>os, to _pos, value) 
Widget widget; 
XmTextPosition from j>os\ 

XmTextPosition to _pos% 

char * value, 

DESCRIPTION 

XmTextReplace replaces part of the text string in the Text widget The character positions begin at 
zero and are numbered sequentially from the beginning of the text 

An example text replacement would be to replace the second and third characters in the text 
string. To accomplish this, the parameter from _pos must be 1 and to _pos must be 3. To insert a 
string after the fourth character, the parameters from _pos and to _pos must both be 4. 

widget Specifies the Text widget ID. 

from _pos Specifies the start position of the text to be replaced. 

to _pos Specifies the end position of the text to be replaced. 

value Specifies the character string value to be added to the text widget 

For a complete definition of Text and its associated resources, see XmText(3X). 



RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextSetEditabk - a Text function that sets the edit permission. 

SYNOPSIS 

#include <Xm/Text.h> 

void XmTextSetEditable (widget, editable) 
Widget widget; 
Boolean editable; 

DESCRIPTION 

XmTextSetEditable sets the edit permission state of the Text widget When set to True, the text 
string can be edited. 

widget Specifies the Text widget ID. 

editable Specifies a Boolean value that when True allows text string edits. 

For a complete definition of Text and its associated resources, see XmText(3X). 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmTextSetMaxLength - a Text function that sets the value of the current maximum allowable 
length of a text string entered from the keyboard. 

SYNOPSIS 

#include <Xm/Text.h> 

void XinTextSetMaxLengtli (widget, max length) 
Widget widget; 
int maxjength; 

DESCRIPTION 

XmTextSetMaxLength sets the value of the current maximum allowable length of the text string in 
the Text widget The maximum allowable length prevents the user from entering a text string from 
the keyboard that is larger than this limit Strings that are entered using the XmNvalue resource 
or the XmTextSetString function ignore this resource. 

widget Specifies the Text widget ID. 

maxjength Specifies the maximum allowable length of the text string. 

For a complete definition of Text and its associated resources, see XmText(3X). 

RELATED INFORMATION 

XmText(3X) and XmTextSetString(3X). 
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NAME 

XmTextSetSekction - a Text function that sets the primary selection of the text. 

SYNOPSIS 

#include <Xm/TexLh> 

void XmTextSetSekction (widget, first, last, time) 
Widget widget; 
XmTextFosition first; 
XmTextPosition last, 
Time time; 

DESCRIPTION 

XmTextSetSekction sets the primary selection of the text in the widget. 

widget Specifies the Text widget ID. 

first Marks the first character position. 

last Marks the last position of the text to be selected. 

time Specifies the time at which the selection value is desired. This should be the same 

time of the event which triggered this request. 

For a complete definition of Text and its associated resources, see XmText (3X). 

RELATED INFORMATION 

XmText(3X). 
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NAME 

XmTextSetString - a Text function that sets the string value. 

SYNOPSIS 

#include <Xm/TextJi> 

void XmTextSetString (widget, value) 
Widget widget; 
char * value, 

DESCRIPTION 

XmTextSetString sets the string value of the Text widget 

widget Specifies the Text widget ID. 

value Specifies the character pointer to the string value and places the string into the 

text edit window. 

For a complete definition of Text and its associated resources, see XmText(3X). 

RELATED INFORMATION 
XmText(3X). 
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NAME 

XmToggleButton - the ToggleButton widget class. 

SYNOPSIS 

#include <Xm/ToggleB.h> 

DESCRIPTION 

ToggleButton sets nontransitory state data within an application. Usually this widget consists of an 
indicator (square or diamond) with either text or a pixmap to its right. However, it can also con- 
sist of just text or a pixmap without the indicator. 

The toggle graphics display a 1-of-many or N-of-many selection state. When a toggle indicator is 
displayed, a square indicator shows a N-of-many selection state and a diamond indicator shows a 
1-of-many selection state. 

ToggleButton implies a selected or unselected state. In the case of a label and an indicator, an 
empty indicator (square or diamond shaped) indicates that ToggleButton is unselected, and a 
filled indicator shows that it is selected. In the case of a pixmap toggle, different pixmaps are used 
to display the selected /unselected states. 

Normally, mouse button 1 is used to arm and activate the button. However, if the ToggleButton 
resides within a menu, then the mouse button used is determined by the RowColumn resources 
XmNrowColumnType and XmNwhichButton. 

To accommodate the toggle indicator when created, Label's resource XmNmarginLeft may be 
increased. 

Classes 

ToggleButton inherits behavior and resources from Core, XmPrimitive, and XmLabel 
Classes. 

The class pointer is xmToggleButtonWidgetCIass. 
The class name is XmToggleButton. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for this widget. To reference a resource by name or by class in a .Xdefaults file, 
remove the XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 
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XmToggleButton Resource Set 


Name 

XmNarmCallback 


Class 

XmCArmCallback 


Type 


Default 


Access 
C 


XtCallbackList 


NULL 


XmNdisarmCallback 


XmCDisarmCallback 


XtCallbackList 


NULL 


C 


XmNfillOnSelect 


XmCFillOnSelect 


Boolean 


True 


CSG 


XmNicdicatorOn 


XmCIndicatorOn 


Boolean 


True 


CSG 


XmNindicatorType 


XmCIndicatorType 


unsigned char 


XmN OF MANY 


CSG 


XmNselect Color 


XmCSelectColor 


Pixel 


dynamic 


CSG 


XmNselectlnsensitivePixmap 


XmCSelectlnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNselectPixmap 


XmCSelectPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNset 


XmCSet 


Boolean 


False 


CSG 


XmNspacing 


XmCSpacing 


short 


4 


CSG 


XmNvalueChangedCallback 


XmCValueChangedCallback 


XtCallbackList 


NULL 


C 


XmNvisibleWhenOff 


XmCVisibleWhenOff 


Boolean 


True 


CSG 



XmNarmCallback 

Specifies the list of callbacks that is called when the ToggleButton is armed. To arm 
this widget, press the active mouse button while the pointer is inside the ToggleBut- 
ton. For this callback, the reason is XmCR_ARM. 

XmNdisarmCallback 

Specifies the list of callbacks that is called when ToggleButton is disarmed. To 
disarm this widget, press and release the active mouse button while the pointer is 
inside the ToggleButton. This widget is also disarmed when the user moves out of 
the widget and releases the mouse button when the pointer is outside the widget 
For this callback, the reason is XmCR_DISARM. 

XmNfiUOnSelect 

Fills the indicator with the color specified in XmNselectColor and switches the top 
and bottom shadow colors when set to True. Otherwise, it switches only the top and 
bottom shadow colors. 

XmNindicatorOn 

Specifies that a toggle indicator is drawn to the left of the toggle text or pixmap 
when set to True. When set to False, no space is allocated for the indicator, and it is 
not displayed. If XmNindicatorOn is True, the indicator shadows are switched 
when the button is selected or unselected, but, any shadows around the entire 
widget are not switched. However, if XmNindicatorOn is False, any shadows 
around the entire widget are switched when the toggle is selected or unselected. 

XmNindicatorType 

Specifies if the indicator is a 1-of or N-of indicator. For the 1-of indicator, the value 
is XmONE OF MANY. For the N-of indicator, the value is XmNOFMANY. The 
N-of-many is a square-shaped indicator. The 1-of-many is a diamond-shaped indi- 
cator. This resource only specifies the visuals and does not enforce the behavior. 
When the ToggleButton is in a RadioBox, the parent forces this resource to 
XmONEOFMANY. 

XmNselectColor 

Allows the application to specify what color fills the center of the square or dia- 
mond indicator when it is set. If this color is the same as either the top or bottom 
shadow color of the indicator, a one-pixel-wide margin is left between the shadows 
•and the fill; otherwise, it is filled completely. This resource's default for a color 
display is a color between the background and bottom shadow color. For a mono- 
chrome display, the default is set to the foreground color. 

XmNselectlnsensitivePixmap 

Specifies a pixmap used as the button face when the ToggleButton is selected and 
the button is insensitive if the Label resource XmNlabelType is set to XmPIXMAP. 
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If the ToggleButton is unselected and the button is insensitive, the pixmap in 
XmNlabellnsensitivePixmap is used as the button face. 

XmNselectPixmap 

Specifies the pixmap to be used as the button face if XmNlabelType is XmPIXMAP 
and the ToggleButton is selected. When the ToggleButton is unselected, the pixmap 
specified in Label's XniNlabelPixmap is used. 

XmNset 

Displays the button in its selected state if set to True. This shows some conditions as 
active when a set of buttons first appear. 

XmNspacing 

Specifies the amount of spacing between the toggle indicator and the toggle label 
(text or pixmap). 

XmNvalueChangedCallback 

Specifies the list of callbacks that is called when the ToggleButton value is changed. 
To change the value, press and release the active mouse button while the pointer is 
inside the ToggleButton. This action also causes this widget to be disarmed. For 
this callback, the reason is XmCR VALUE CHANGED. 

XmNvisibleWhenOff 

Indicates that the toggle indicator is visible in the unselected state when the Boolean 
value is True. When the ToggleButton is in a menu, the RowColumn parent forces 
this resource to False. When the ToggleButton is in a RadioBox, the parent forces 
this resource to True. 



Inherited Resources 

ToggleButton inherits behavior and resources from the following superclasses. For a com- 
plete description of these resources, refer to the man page for that superclass. 



XmLabel Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerator 


XmCAccelerator 


String 


NULL 


CSG 


XmNacceleratorText 


XmCAcceleratoiText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFostList 


•Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFlED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


0 


CSG 


XmNmargjnHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


dynamic 


CSG 


XmNmarginRight 


XmCMarginRight 


short 


0 


CSG 


XmNmarginTop 


XmCMarginTop 


short 


0 


CSG 


XmNmargmWidth 


XmCMarginWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


AO- 


CSG 


XmNrecomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 
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Xm Primitive Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNbottomShadowColor 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNbottomShadowPixmap 


XmCBottornShadcwPixiriap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNforcground 


XmCForeground 


Pixel 


dynamic 


CSG 


XmNhelpCallback 


XmCCallbadc 


XtCallbackList 


NULL 


c 


XmNhighlightColor 


XmCForeground 


Pixel 


Black 


CSG 


XmNhighlightOnEnter 


XmCHighlightOnEnter 


Boolean 


False 


CSG 


ymNhigMighfPiYmap 


XmCHighlightPixmap 




dynamic 


CSG 


XmNMghlightThickness 


XmCHighlightThickness 


"sliorF 


0 


CSG 


XmNshadcnThickness 


XmCShadowThickness 


short 


0 


CSG 


XmNtopShadcwColor 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNtopShadcwPixmap 


XmCTopShadcwPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitType 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 




Core Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerators 


XmCAccelerators 


XtTranslations 


NULL 


CSG 


XmNancestorSensitive 


XmCSensitive 


Boolean 


True 


G 


XmNbackground 


XmCBadcground 


Pixel 


dynamic 


CSG 


XmNbackgroundPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderColor 


XmCBorderColor 


Pixel 


Black 


CSG 


XmNborderPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNcolormap 


XmCColormap 


Colormap 


XtCopyFromParent 


CG 


XmNdepth 


XmCDepth 


int 


XtCopyFromParent 


CG 


XmNdestroyCallback 


XmCCallback 


XtCallbadcList 


NULL 


C 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNmappedWhenManaged 


XrnCMappedWhenManaged 


Boolean 


True 


CSG 


XmNscreen 


XmCScreen 


Pointer 


XtCopyScreen 


CG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNtranslations 


XmCTranslations 


XtTranslations 


NULL 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XmNy 


XmCPosition 


Position 


0 


CSG 



Callback Information 

The following structure is returned with each callback: 

typedef struct 
{ 

int reason; 
XEvent * event; 

Boolean set; 
} XmToggleButtonCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

set Reflects the ToggleButton's current state when the callback occurred, either 

True (selected) or False (unselected). 
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Behavior 

ToggleButton is associated with the default behavior unless it is part of a menu system. In a 
menu system, the RowColumn parent determines which mouse button is used. 



Default Behavior 
<BtnlDown>: 

(if unset): This action arms the ToggleButton widget The indicator shadow is 
drawn so that the button looks depressed, and the indicator fills with the color 
specified in XmNselectColor. The callbacks for XmNarmCallback are also called. 

(if set): This action arms the ToggleButton widget The indicator shadow is drawn 
so that the button looks raised, and the indicator fills with the background color. 
The callbacks for XmNarmCallback are also called. 

<BtnlUp>: 

(In Button): 

(if unset): This action selects the ToggleButton widget. Visually, it appears the 
same as when it is armed. The callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButton widget. Visually, it appears the 
same as when it is armed. The callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

(Outside Of Button): 

If the button release occurs outside of the ToggleButton, the callbacks for 
XmNdisarmCallback are called. 

< Leave Window > : 

If the button is pressed and the cursor leaves the widget, it visually reverts to its pre- 
vious unpressed state. 

< Enter Window >: 

If the button is pressed and the cursor leaves and reenters the widget, it visually 
appears the same as when the button was first armed. 



Default PopupMenu System 
<Btn3Down>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
This action also causes the ToggleButton to be armed. A shadow is drawn around 
the ToggleButton. The callbacks for XmNarmCallback are also called. 

<Btn3Up>: 

(if unset): This action selects the ToggleButton widget. The indicator shadow is 
drawn so that it looks depressed, and the indicator fills with the color specified in 
XmNselectColor. The menu is then unposted and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButton widget The indicator shadow is 
drawn so that it looks raised, and the indicator fills with the background color. The 
menu is then unposted and the callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

< Leave Window > : 

Pressing button 3 and moving the cursor out of the widget's window erases the sha- 
dow around the ToggleButton. This event is ignored if keyboard traversal is 
enabled in the menu. 

< Enter Window >: 

Pressing button 3 and moving the cursor into the widget's window draws a shadow 
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around the ToggleButton. This event is ignored if keyboard traversal is enabled in 
the menu. 

<Key>Return: 

If keyboard traversal is enabled in the menu, this event sets or unsets the Tog- 
gleButton. 

(if unset): The ToggleButton gets set. The indicator shadow is drawn so that looks 
depressed, and the indicator fills with the color specified in XmNselectColor. 

(if set): The ToggleButton gets unset. The indicator shadow is drawn so that it 
looks raised, and the indicator fills with the background color. 

For both set and unset cases, the menu is then unposted and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

Default Pulldown Menu System and OptionMenu System 
<BtnlDown>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode (the mode in which the menu is manipulated using the mouse). This action 
also arms the ToggleButton. A shadow is drawn around the ToggleButton. The 
callbacks for XmNarmCallback are also called. 

<BtnlUp>: 

(if unset): This action selects the ToggleButton. The indicator shadow is drawn so 
that it looks depressed, and the indicator fills with the color specified in 
XmNselectColor. The menu then imposts, and the callbacks for XmvalueChanged- 
Callback are called, followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButton. The indicator shadow is drawn so 
that it looks raised, and the indicator fills with the background color. The menu 
then unposts, and the callbacks for XmvalueChangedCallback are called, followed 
by callbacks for XmdisarmCallback. 

< Leave Window > : 

Pressing button one and moving the cursor out of the widget's window erases the 
shadow around the ToggleButton. This event is ignored if keyboard traversal is 
enabled in the menu. 

< Enter Window >: 

Pressing button one and moving the cursor into the widget's window draws a sha- 
dow around the ToggleButton. This event is ignored if keyboard traversal is 
enabled in the menu. 

< Key > Return: 

This event sets or unsets the ToggleButton if keyboard traversal is enabled in the 
menu. 

(if unset): The ToggleButton gets set. The indicator shadow is drawn so that it 
looks depressed, and the indicator fills with the color specified in XmNselectColor. 

(if set): The ToggleButton gets unset. The indicator shadow is drawn so that it 
looks raised, and the indicator fills with the background color. 

For both set and unset cases, the menu then unposts, and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

Default Translations 

When not in a menu system, the following are the default translations: 

<BtnlDown>: Arm() 
<BtnlUp>: Select() 
Disarm() 
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< Key > Return: ArmAndActivate() 

< Key > space: ArmAndActivateO 
<EnterWindow>: Enter() 

< LeaveWindow > : Leave() 

When in a menu system, the following are the default translations: 

<BtnDown>: BtnDownO 

<BtnUp>: BtnUp() 

<EnterWindow>: Enter() 

< LeaveWindow > : Leave() 
<Key>Return: KeySelect() 

< Key > Escape: MenuShellPopdownDone() 

Keyboard Traversal 

When in a menu system, the following translations are added to ToggleButton. 

<Unmap>: UnmapO 
<FocusOut>: FocusOut() 
<FocusIn>: FocusInO 

< Key > space: Noop() 

< Key > Left: MenuTVaverseLeft() 
<Key>Right: MenulraverseRight() 
<Key>Up: MenuTraverseUpO 

< Key > Down: MenulraverseDown() 

< Key > Home: Noop() 

For information on keyboard traversal when not in a menu, see the man page for 

XmPrimitive(3X) and its sections on behavior and default translations. 

RELATED INFORMATION 

Core(3X), XmCreateToggleButton(3X), XmLabel(3X), XmPrimitive(3X), XmRowColumn(3X), 
XmToggleButtonGetState(3X), and XmToggIeButtonSetState(3X). 
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NAME 

XmToggleButtonGadget - the ToggleButtonGadget widget class. 

SYNOPSIS 

#include <Xm/IbggIeBG.h> 

DESCRIPTION 

ToggleButtonGadget sets nontransitoiy state data within an application. Usually this gadget con- 
sists of an indicator (square or diamond) with either text or a pixmap to its right. However, it can 
also consist of just text or a pixmap without the indicator. 

The toggle graphics display a 1-of-many or N-of-many selection state. When a toggle indicator is 
displayed, a square indicator shows a N-of-many selection state and a diamond indicator shows a 
1-of-many selection state. 

ToggleButtonGadget implies a selected or unselected state. In the case of a label and an indicator, 
an empty indicator (square or diamond shaped) indicates that ToggleButtonGadget is unselected, 
and a filled indicator shows that it is selected. In the case of a pixmap toggle, different pixmaps 
are used to display the selected /unselected states. 

Normally, mouse button 1 is used to arm and activate the button. However, if the ToggleBut- 
tonGadget resides within a menu, then the mouse button used is determined by the RowColumn 
resources XmNrowColumnType and XmNwhichButton, 

To accommodate the toggle indicator when created, Label's resource XntNmarginLeft may be 
increased. 

Classes 

ToggleButtonGadget inherits behavior and resources from Object, RectObj, XmGadget and 
XmLabelGadget classes. 

The class pointer is xmToggleButtonGadgetClass. 
The class name is XmToggleButtonGadget. 

New Resources 

The following table defines a set of widget resources used by the programmer to specify 
data. The programmer can also set the resource values for the inherited classes to set attri- 
butes for mis widget To reference a resource by name or by class in a .Xdefaults file, 
remove die XmN or XmC prefix and use the remaining letters. To specify one of the 
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remain- 
ing letters (in either lower case or upper case, but include any underscores between words). 
The codes in the access column indicate if the given resource can be set at creation time (C), 
set by using XtSetValues (S), retrieved by using XtGet Values (G), or is not applicable (N/A). 
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XmToggkButtonGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNarmCallback 


XmCArmCallback 


XtCallbackList 


NULL 


C 


XmNdisarmCallback 


XmCDisarmCallback 


XtCallbackList 


NULL 


C 


XmNfillOnSelect 


XmCKllOiiSelect 


Boolean 


True 


CSG 


XmNindicatorOn 


XmCIndicatorOn 


Boolean 


True 


CSG 


XmNindicatoiType 


XmCIndicatorType 


unsigned char 


XmN OF MANY 


CSG 


XmN select Color 


XmCSelect Color 


Pixel 


dynamic 


CSG 


XmNselectlnsensithrePixmap 


XmCSelectlnsensitivePixmap 


Pixmap 


XmUNSPECIFIED_PIXMAP 


CSG 


XmNselectPixmap 


XmCSelectPixmap 


Pixmap 


XmUNSPECIFIEDPIXMAP 


CSG 


XmNset 


XmCSet 


Boolean 


False 


CSG 


XmNspacing 


XmCSpacing 


short 


4 


CSG 


XmNvalueChangedCallback 


XmCValueChangedCallback 


XtCallbackList 


NULL 


C 


XmNvisibleWhenOff 


XmCVisibleWnenOff 


Boolean 


True 


CSG 



XmNarmCallback 

Specifies a list of callbacks that is called when the ToggleButtonGadget is armed. To 
arm this gadget, press the active mouse button while the pointer is inside the Tog- 
gleButtonGadget. For this callback, the reason is XmCR_ARM. 

XmNdisarmCallback 

Specifies a list of callbacks that is called when ToggleButtonGadget is disarmed. To 
disarm this gadget, press and release the active mouse button while the pointer is 
inside the ToggleButtonGadget. The gadget is also disarmed when the user moves 
out of the gadget and releases the mouse button when the pointer is outside the 
gadget. For this callback, the reason is XmCR_DISARM. 

XmNfillOnSelect 

Fills the indicator with the color specified in XmNselectColor and switches the top 
and bottom shadow colors when set to True. Otherwise, it switches only the top and 
bottom shadow colors. 

XmNindicatorOn 

Specifies that a toggle indicator is drawn to the left of the toggle text or pixmap 
when set to True. When set to False, no space is allocated for the indicator, and it is 
not displayed. If XmNindicatorOn is True, the indicator shadows are switched 
when the button is selected or unselected, but any shadows around the entire gadget 
are not switched. However, if XmNindicatorOn is False, any shadows around the 
entire gadget are switched when the toggle is selected or unselected. 

XmNindicatoiType 

Specifies if the indicator is a 1-of or N-of indicator. For the 1-of indicator, the value 
is XmONEOFMANY. For the N-of indicator, the value is XmNOFMANY. The 
N-of-many is a square-shaped indicator. The 1-of-many is a diamond-shaped indi- 
cator. This resource only specifies the visuals and does not enforce the behavior. 
When the ToggleButtonGadget is in a RadioBox, the parent forces this resource to 
XmONEOFMANY. 

XmNselectColor 

Allows the application to specify what color fills the center of the square or dia- 
mond indicator when it is set. If this color is the same as either the top or bottom 
shadow color of the indicator, a one-pixel-wide margin is left between the shadows 
and the fill; otherwise, it is filled completely. This resource's default for a color 
display is a color between the background and bottom shadow color. For a mono- 
chrome display, the default is set to the foreground color. 

XmNselectlnsensitivePixmap 

Specifies a pixmap used as the button face when the ToggleButtonGadget is selected 
and the button is insensitive if the LabelGadget resource XmNlabelType is 
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XmPIXMAP. If the ToggleButtonGadget is unselected and the button is insensitive, 
the pixmap in XmNlabellnsensitivePixmap is used as the button face. 

XmNselectPixmap 

Specifies the pixmap to be used as the button face if XmNlabelType is XmPIXMAP 
and the ToggleButtonGadget is selected. When the ToggleButtonGadget is 
unselected, the pixmap specified in Label's XmNlabelPixmap is used. 

XmNset 

Displays the button in its selected state if set to True. This shows some conditions as 
active when a set of buttons first appear. 

XmNspacing 

Specifies the amount of spacing between the toggle indicator and the toggle label 
(text or pixmap). 

XmNvalueChangedCallback 

Specifies a list of callbacks that is called when the ToggleButtonGadget value is 
changed. To change the value, press and release the active mouse button while the 
pointer is inside the ToggleButtonGadget This action also causes the gadget to be 
disarmed. For this callback, the reason is XmCR_VALUE_CHANGED. 

XmNvisibleWhenOff 

Indicates that the toggle indicator is visible in the unselected state when the Boolean 
value is True. When the ToggleButtonGadget is in a menu, the RowColumn parent 
forces this resource to False. When the ToggleButtonGadget is in a RadioBox, the 
parent forces this resource to True. 



Inherited Resources 

ToggleButtonGadget inherits behavior and resources from the following superclasses. For a 
complete description of these resources, refer to the man page for that superclass. 



XmLabelGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNaccelerator 


XmCAccelerator 


String 


NULL 


CSG 


XmNacceleratoiText 


XmCAcceleratoiText 


XmString 


NULL 


CSG 


XmNalignment 


XmCAlignment 


unsigned char 


XmALIGNMENT CENTER 


CSG 


XmNfontList 


XmCFontList 


XmFontList 


"Fixed" 


CSG 


XmNlabellnsensitivePixmap 


XmCLabellnsensitivePixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelPixmap 


XmCPixmap 


Pixmap 


XmUNSPECIFIED PIXMAP 


CSG 


XmNlabelString 


XmCXmString 


XmString 


NULL 


CSG 


XmNlabelType 


XmCLabelType 


unsigned char 


XmSTRING 


CSG 


XmNmarginBottom 


XmCMarginBottom 


short 


0 


CSG 


XmN marginHeight 


XmCMarginHeight 


short 


2 


CSG 


XmNmarginLeft 


XmCMarginLeft 


short 


dynamic 


CSG 


XmNmarginRight 


XmCMarginRighi 


short 


0 


CSG 


XmNmarginTap 


XmCMarginTop 


short 


0 


CSG 


XmNmarginWidth 


XmCMarginWidth 


short 


2 


CSG 


XmN mnemonic 


XmCMnemonic 


char 


•\0' 


CSG 


XmN recomputeSize 


XmCRecomputeSize 


Boolean 


True 


CSG 


XmNstringDirection 


XmCStringDirection 


XmStringDirection 


XmSTRING DIRECTION L TO R 


CSG 
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XmGadget Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNhelpCallback 


XmCCallback 


XtCaUbackList 


NULL 


C 


XmNhighlightOnEnter 


XmCHighlightOnEnler 


Boolean 


False 


CSG 


XmNhighnghrThickness 


XmCHighlightTbickoess 


short 


0 


CSG 


XniNshadowThickness 


XmCShadcwThidcncss 


short 


0 


CSG 


XmNtraversalOn 


XmCTraversalOn 


Boolean 


False 


CSG 


XmNunitTVpe 


XmCUnitType 


unsigned char 


XmPIXELS 


CSG 


XmNuserData 


XmCUserData 


caddr t 


NULL 


CSG 



RectOty Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNancestorSensitive 


XmCSensitive 


Boolean 


XtCopyFromParent 


CSG 


XmNborderWidth 


XmCBorderWidth 


Dimension 


0 


CSG 


XmNheight 


XmCHeight 


Dimension 


0 


CSG 


XmNsensitive 


XmCSensitive 


Boolean 


True 


CSG 


XmNwidth 


XmCWidth 


Dimension 


0 


CSG 


XmNx 


XmCPosition 


Position 


0 


CSG 


XroNy 


XmCPosition 


Position 


0 


CSG 



Object Resource Set 


Name 


Class 


Type 


Default 


Access 


XmNdestroyCallback 


XmCCallback 


XtCaUbackList 


NULL 


C 



Callback Information 

The following structure is returned with each callback: 

typedef struct 

{ 

int reason; 
XEvent * event, 

Boolean set; 
} XmToggleButtonCallbackStruct; 

reason Indicates why the callback was invoked. 

event Points to the XEvent that triggered the callback. 

set Reflects the ToggleButtonGadget's current state when the callback occurred, 

either True (selected) or False (unselected). 

Behavior 

ToggleButtonGadget is associated with the default behavior unless it is part of a menu sys- 
tem. In a menu system, the RowColumn parent determines which mouse button is used. 

Default Behavior 
<BtnlDown>: 

(if unset): This action arms the ToggleButtonGadget The indicator shadow is 
drawn so that the button looks depressed, and the indicator fills, with the color 
specified in XmNselectColor. The callbacks for XmNarmCallback are also called. 

(if set): This action arms the ToggleButtonGadget. The indicator shadow is drawn 
so that the button looks raised, and the indicator fills with the background color. 
The callbacks for XmNarmCallback are also called. 



Hewlett-Packard Company 



-4- 



Aug 28,1989 



XmToggfcButtonGadget (3X) 



XmToggkButtonGadget (3X) 



<BtnlUp>: 

(In Button): 

(if unset): This action selects the ToggleButtonGadget. Visually, it appears the 
same as when it is armed. The callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButtonGadget. Visually, it appears the 
same as when it is armed. The callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

(Outside Of Button): 

If the button release occurs outside of the ToggleButtonGadget, the callbacks for 
XmNdisarmCallback are called. 

< Leave Window > : 

If the button is pressed and the cursor leaves the gadget, it visually reverts to its pre- 
vious unpressed state. 

< Enter Window >: 

If the button is pressed and the cursor leaves and reenters the gadget, it visually 
appears the same as when the button was first armed. 

Default PopupMenu System 
<Btn3Down>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode, which is the mode in which the menu is manipulated by using the mouse. 
This action also causes the ToggleButtonGadget to be armed. A shadow is drawn 
around the ToggleButtonGadget The callbacks for XmNarmCallback are also 
called. 

<Btn3Up>: 

(if unset): This action selects the ToggleButtonGadget. The indicator shadow is 
drawn so that it looks depressed, and the indicator fills with the color specified in 
XmNselectColor. The menu is then unposted and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButtonGadget. The indicator shadow is 
drawn so that it looks raised, and the indicator fills with the background color. The 
menu is then unposted and the callbacks for XmvalueChangedCallback are called, 
followed by callbacks for XmdisarmCallback. 

< Leave Window >: 

Pressing button 3 and moving the cursor out of the widget's window erases the sha- 
dow around the ToggleButtonGadget. This event is ignored if keyboard traversal is 
enabled in the menu. 

< Enter Window >: 

Pressing button 3 and moving the cursor into the widget's window draws a shadow 
around the ToggleButtonGadget. This event is ignored if keyboard traversal is 
enabled in the menu. 

<Key>Return: 

If keyboard traversal is enabled in the menu, this event sets or unsets the Tog- 
gleButtonGadget. 

(if unset): The ToggleButtonGadget gets set. The indicator shadow is drawn so 
that looks depressed, and the indicator fills with the color specified in 
XmN selectColor. 

(if set): The ToggleButtonGadget gets unset. The indicator shadow is drawn so 
that it looks raised, and the indicator fills with the background color. 
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For both set and unset cases, the menu is then unposted and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

Default PulldownMenu System and OptionMenu System 
<BtnlDown>: 

This action disables keyboard traversal for the menu and returns the user to drag 
mode (the mode in which the menu is manipulated using the mouse). This action 
also arms the ToggleButtonGadget. A shadow is drawn around the ToggleBut- 
tonGadget. The callbacks for XmNarmCallback are also called. 

<BtnlUp>: 

(if unset): This action selects the ToggleButtonGadget. The indicator shadow is 
drawn so that it looks depressed, and the indicator fills with the color specified in 
XmNselectColor. The menu then imposts, and the callbacks for XmvalueChanged- 
Callback are called, followed by callbacks for XmdisarmCallback. 

(if set): This action unselects the ToggleButtonGadget. The indicator shadow is 
drawn so that it looks raised, and the indicator fills with the background color. The 
menu then unposts, and the callbacks for XmvalueChangedCallback are called, fol- 
lowed by callbacks for XmdisarmCallback. 

< Leave Window > : 

Pressing button one and moving the cursor out of the widget's window erases the 
shadow around the ToggleButtonGadget This event is ignored if keyboard traver- 
sal is enabled in the menu. 

< Enter Window >: 

Pressing button one and moving the cursor into the widget's window draws a sha- 
dow around the ToggleButtonGadget. This event is ignored if keyboard traversal is 
enabled in the menu. 

< Key > Return: 

This event sets or unsets the ToggleButtonGadget if keyboard traversal is enabled in 
the menu. 

(if unset): The ToggleButtonGadget gets set. The indicator shadow is drawn so that 
it looks depressed, and the indicator fills with the color specified in 
XmNselectColor. 

(if set): The ToggleButtonGadget gets unset. The indicator shadow is drawn so 
that it looks raised, and the indicator fills with the background color. 

For both set and unset cases, the menu then unposts, and the callbacks for 
XmvalueChangedCallback are called, followed by callbacks for XmdisarmCallback. 

Keyboard Traversal 

For information on keyboard traversal when not in a menu system, see the man page for 
XmGadget(3X) and its sections on behavior and default translations. When the ToggleBut- 
tonGadget is in a menu system, the keyboard traversal translations are defined by the 
RowColumn parent. 

RELATED INFORMATION 

Object(3X), RectObj(3X), XmCreateToggleButtonGadget(3X), XmGadget(3X), 
XmLabelGadget(3X), XmRowCoIumn(3X), XmToggleButtonGadgetGetState(3X), and 
XmToggleButtonGadgetSetState(3X). 
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NAME 

XmToggleButtonGadgetGetState - a ToggleButtonGadget function that obtains the state of a 
ToggleButtonGadget. 

SYNOPSIS 

#include <Xm/ToggleBG.h> 

Boolean XmToggleButtonGadgetGetState (widget) 
Widget widget; 

DESCRIPTION 

XmToggleButtonGadgetGetState obtains the state of a ToggleButtonGadget. 
widget Specifies the ToggleButtonGadget ID. 

For a complete definition of ToggleButtonGadget and its associated resources, see 
XmToggleButtonGadget(9X). 

RETURN VALUE 

Returns True if the button is selected and False if the button is unselected. 

RELATED INFORMATION 

XmToggleButtonGadget(3X). 
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NAME 

XnffbggleButtonGadgetSetState - a ToggleButtonGadget function that sets or changes the 
current state.. 

SYNOPSIS 

#include <Xm/ToggleBG.h> 

void XinToggleButtonGadget Set State {widget, state, notify) 
Widget widget; 
Boolean state; 
Boolean notify; 

DESCRIPTION 

XmToggleButtonGadget SetState sets or changes the ToggleButtonGadget's current state. 
widget Specifies the ToggleButtonGadget widget ID. 

state Specifies a Boolean value that indicates whether the ToggleButtonGadget state is 

selected or unselected. If True, the button state is selected; if False, the button 
state is unselected. 

notify Indicates whether XmNvalueChangedCallback is called; it can be either True or 

False. 



For a complete definition of ToggleButtonGadget and its associated resources, see 
XmToggleButtonGadget(3X). 

RELATED INFORMATION 

XmToggleButtonGadget(3X). 
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NAME 

XnflbggleButtonGetState - a ToggleButton function that obtains the state of a ToggleButton. 

SYNOPSIS 

#include <Xm/ToggleB.h> 

Boolean XmToggleButtonGetState {widget) 
Widget widget} 

DESCRIPTION 

XnfloggleBnttonGetState obtains the state of a ToggleButton. 
widget Specifies the ToggleButton widget ID. 

For a complete definition of ToggleButton and its associated resources, see XmToggleButton(3X). 
RETURN VALUE 

Returns True if the button is selected and False if the button is unselected. 

RELATED INFORMATION 

XmToggleButton(3X). 
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NAME 

XmToggleButtonSetState - a ToggleButton function that sets or changes the current state. 

SYNOPSIS 

#include <Xm/ToggleB.h> 

void XmToggleButtonSetState (widget, state, notify) 
Widget widget; 
Boolean state; 
Boolean notify; 

DESCRIPTION 

XinToggleButtonSetState sets or changes the ToggleButton's current state. 
widget Specifies the ToggleButton widget ID. 

state Specifies a Boolean value that indicates whether the ToggleButton state is selected 

or unselected. If True, the button state is selected; if False, the button state is 
unselected. 

notify Indicates whether XmNvalueChangedCallback is called; it can be either True or 

False. 

For a complete definition of ToggleButton and its associated resources, see XmToggleButton(3X). 

RELATED INFORMATION 

XmToggIeButton(3X). 
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NAME 

XmUninstalllmage - a pixmap caching function that removes an image from the image cache. 

SYNOPSIS 

#include <Xm/Xm.h> 

Boolean XmUninstalllmage {image) 

Xlmage * image; 

DESCRIPTION 

XmUninstalllmage removes an image from the image cache. 
image Points to the image structure given to the Xmlnstalllmage() routine. 

RETURN VALUE 

Returns True when successful; returns False if the image is NULL or if it cannot be found to be 
uninstalled. 

RELATED INFORMATION 

XmInstallImage(3X), XmGetPixmap(3X), and XmDestroyPixmap(3X). 
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NAME 



XmUpdateDisplay - a function that processes all pending exposure events immediately. 



XmUpdateDisplay provides the application with a mechanism for forcing all pending exposure 
events to be removed from the input queue and to be processed immediately. 

When a user selects a button within a MenuPane, the MenuPanes are unposted and then any 
activation callbacks registered by the application are invoked. If one of the callbacks performs a 
time-consuming action, the portion of the application window which had been covered by the 
MenuPanes will not have been redrawn; normal exposure processing does not occur until all of 
the callbacks have been invoked. If the application writer suspects that a callback will take a long 
time, then the callback may choose to invoke XmUpdateDisplay before starting its time-consuming 
operation. 

This function is also useful any time a transient window is unposted, such as a dialog box; call- 
backs are invoked before normal exposure processing can occur. 

widget Specifies any widget or gadget. 



SYNOPSIS 



void XmUpdateDisplay (widget) 
Widget w 



widget, 



DESCRIPTION 
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NAME 

XtDisplaylnitialize - a function that initializes the toolkit's view of a display and adds it to an 
application context. 



SYNOPSIS 

#include <Xm/Xm.h> 



Widget XtDisplaylnitialize (app_context, 
numjjptions, argc, argv) 

XtAppContext 

Display 

String 

String 

XrmOptionDescRec 
Cardinal 
Cardinal 
String 



display, application jiame, application jdass, options, 

app_contexf, 

* display; 
application jiame; 
application jzlass; 
options; 
num_options; 

* <*fP, 
orgy, 



DESCRIPTION 

XtDisplaylnitialize parses the command line that invoked the application, and loads the resource 
database. XtDisplaylnitialize is a back-end routine that is usually called be Xtlnitialize. It may be 
called directly if the application needs to open more than one display. XtDiplaylnitialize is passed 
an open display. XtOpenDisplay can be used in the case where an open display has not yet been 
generated. 

By passing the command line that invoked your application to XtDisplaylnitialize, the function 
can parse the line to allow users to specify certain resources (such as fonts and colors) for your 
application at run time. XtDisplaylnitialize scans the command line and removes those options. 
The rest of your application sees only the remaining options. 

XtDisplaylnitialize supports localization of defaults files based on the value of the LANG 
environment variable. The user can specify a language by using the LANG environment variable. 
Elements of this variable are then used to establish a path to the proper resource files. The fol- 
lowing substitutions are used in building the path: 

• %N is replaced by class name of the application. 

• %L is replaced by the value of LANG environment variable. 

• %l is replaced by the language part of LANG environment variable. 

• %t is replaced by the territory part of LANG environment variable. 

• %c is replaced by the code set part of LANG environment variable. 

• %% is replaced by %. 

If the LANG environment variable is not defined, or if one of its parts is missing, then a % ele- 
ment that references it is replaced by NULL. 

The paths contain a series of elements separated by colons. Each element denotes a file name, 
and the file names are looked up left to right till one of them succeeds. Before doing the lookup, 
substitutions are performed. 

NOTE: We are using the X/Open convention of collapsing multiple adjoining slashes in a 
filename into one slash. 

The Xtlnitalize function loads the resource database by merging in resources from these sources: 

• Application-specific class resource file on the local host. 

• Application-specific user resource file on the local host. 

• Resource property on the server or user preference resource file on the local host. 

• Per-host user environment resource file on the local host 
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• The application command line (argv). 

To load the application-specific class resource file, XtDisplaylnitialize performs the appropriate 
substitutions on this path: 

• /usr/lib/Xll/%L/app-defaults/%N:/asr/Ub/Xll/app-defaults/%N 

If LANG environment variable is not defined (or the first path lookup using LANG fails), then the 
lookup will default to the current non-language specific location 
(/usr/lib/Xll/app_defaults/%N). 

To load the user's application resource file, XtDisplaylnitialize performs the following steps: 

• Use XAPPLRESLANGPATH environment variable to look up the file. A possible value for 
XAPPLRESLANGDIR is: 

7%N:$HOME/app-defaults/%L/%N:$HOME/app-defaults/%N:$HOME/%L/%N:$HOME/%N 

• If that fails, or if XAPPLPRESLANGPATH is not defined, and if XAPPLRESDIR is defined, 
use the following as the path: 

%XAPPLRESDIR%L/%N:%XAPPLRESDIR%N 



$HOME/%L/%N:$HOME/%N 

Note that if the XAPPLRESLANGPATH lookup is not successful and LANG is not defined the 
lookup is then equivalent to that used by the R3 specification of Xtlnitialize (actually described 
under XtDisplaylnitialize). 

The parameters for XtDisplaylnitialize are defined below: 
app context Specifies the application context. 

display Specifies the display. Note that a display can be in at most one applica- 



else use: 



tion context. 



application jiame 
application _class 



Specifies the name of this application. 



Specifies the class name of this application, which usually is the generic 
name for all instances of this application. By convention, the class name 
is formed by reversing the case of the application's first letter. The class 
name is used to locate the files used to initialize the resource database. 



options 



Specifies how to parse the command line for any application-specific 
resources. The options argument is passed as a parameter to XrmPar- 
seCommand. 



num_options 



Specifies the number of entries in options list. 



ar&> 



argc 



Specifies a pointer to the number of command line parameters. 
Specifies the command line parameters. 



RELATED INFORMATION 
XtInitialize(3X). 
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NAME 

XtGrabKey - a function that establishes a passive grab on the specified keys. 



SYNOPSIS 

#include <Xm/Xm.h> 

void XtGrabKey (widget, keycode, modifiers, owner jvents, pointer jnode, keyboard jnode) 

Widget widget; 

Keycode keycode; 

unsigned int modifiers} 

Boolean owner jvents; 

int pointer jnode; 

int keyboard mode; 



DESCRIPTION 

XtGrabKey establishes a passive grab on the specified keys, such that when the specified 
key/modifier combination is pressed, the keyboard is grabbed. It also allows the client to redirect 
the specified key event to the root widget of a hierarchy. 



widget 

keycode 
modifiers 



owner jvents 
pointer jnode 
keyboard jnode 



Specifies the root widget to the XtGrabKeyboard call. All key events 
that would have been dispatched to other subwindows will get 
dispatched to it subject to owner jvents. 

Specifies the Keycode. This maps to the specific key to be grabbed. 

Specifies the set of keymasks. This mask is the bitwise inclusive OR of 
these keymask bits: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. You can also pass 
AnyModifier, which is equivalent to issuing the grab key request for all 
possible modifier combinations, including the combination of no 
modifiers. 

Specifies if the pointer events are to be reported normally (True) or 
with respect to the grab window if selected by the event mask (False). 

Specifies further processing of pointer events. You can pass GrabMo- 
deSync or GrabModeAsync. 

Specifies further processing of keyboard events. You can pass Grab- 
ModeSync or GrabModeAsync. 



RELATED INFORMATION 

XGrabKey(3X) and XtUngrabKey(3X). 
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NAME 

XtGrabKeyboard - a function that actively grabs control of the main keyboard. 

SYNOPSIS 

#include <Xll/PassivGrab.h> 

int XtGrabKeyboard (widget, owner jvents, pointer jnode, keyboard jnode, time) 
Widget widget; 
Boolean owner events; 

int pointer jnode; 
int keyboard jnode; 
Time time; 

DESCRIPTION 

XtGrabKeyboard actively grabs control of the main keyboard. If the grab is successful, it returns 
the constant GrabSuccess. Further key events are reported to the grab widget 

widget Specifies the root widget to the XtGrabKeyboard call. All key events 

that would have been dispatched to other subwindows will get 
dispatched to it subject to owner jvents. 

owner _events Specifies if the pointer events are to be reported normally (True) or 

with respect to the grab window if selected by the event mask (False). 

pointer jnode Specifies further processing of pointer events. You can pass GrabMo- 

deSync or GrabModeAsync. 

keyboard jnode Specifies further processing of keyboard events. You can pass Grab- 

ModeSync or GrabModeAsync. 

time Specifies the time. You can pass either a timestamp, expressed in mil- 

liseconds, or CurrentTime. 

RETURN VALUE 

Returns the constant GrabSuccess. 



RELATED INFORMATION 

XtUngrabKeyboard(3X). 
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NAME 

Xtlnitialize - a function that initializes the toolkit and returns a top-level shell 

SYNOPSIS 

#include <Xm/Xm.h> 

Widget Xtlnitialize {shell jtame, application class, options, numjoptions, argc, argv) 
String shell jiame; 
String application class; 

XrmOptionDescRec options; 
Cardinal num _options; 

Cardinal * argc, 

String orgy, 

DESCRIPTION 

The Xt Intrinsics must be initialized before making any other calls to Xt Intrinsics functions. 
Xtlnitialize establishes the connection to the display server, parses the command line that invoked 
the application, loads the resource database, and creates a shell widget to serve as the parent of 
your application widget hierarchy. 

Bypassing the command line that invoked your application to Xtlnitialize, the function can parse 
the line to allow users to specify certain resources (such as fonts and colors) for your application 
at run time. Xtlnitialize scans the command line and removes those options. The rest of your 
application sees only the remaining options. 

There is an alternate set of functions that you can use to initialize the Xt Intrinsics that is not as 
convenient as Xtlnitialize; however, it is more flexible because it lets you decide the type of shell 
you want to use. The function XtToolkitlnitialize just initializes the toolkit. It does not open the 
display or create an application shell. You must do this yourself using XtOpenDisplay and 
XtAppCreateShell. 

Xtlnitialize supports localization of defaults files based on the value of the LANG environment 
variable. The user can specify a language by using the LANG environment variable. Elements of 
this variable are then used to establish a path to the proper resource files. The following substitu- 
tions are used in building the path: 

• %N is replaced by class_name of the application. 

• %L is replaced by the value of LANG environment variable. 

• %l is replaced by the language part of LANG environment variable. 

• %t is replaced by the territory part of LANG environment variable. 

• %c is replaced by the code set part of LANG environment variable. 

• %% is replaced by %. 

If the LANG environment variable is not defined, or if one of its parts is missing, then a % ele- 
ment that references it is replaced by NULL. 

The paths contain a series of elements separated by colons. Each element denotes a file name, 
and the file names are looked up left to right till one of them succeeds. Before doing the lookup, 
substitutions are performed. 

NOTE: We are using the X/Open convention of collapsing multiple adjoining slashes in a 
filename into one slash. 

The Xtlnitalize function loads the resource database by merging in resources from these sources: 

• Application-specific class resource file on the local host. 

• Application-specific user resource file on the local host. 

• Resource property on the server or user preference resource file on the local host. 
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• Per-host user environment resource file on the local host 

• The application command line (argv). 

To load the application-specific class resource file, Xtlnitialize performs the appropriate substitu- 
tions on this path: 

• /usr/lib/Xll/%L/app-defaults/%N:/usr/lib/Xll/app-defaults/%N 

If LANG environment variable is not defined (or the first path lookup using LANG fails), then the 
lookup will default to the current non-language specific location 
(/usr/lib/Xll/app_defaults/%N). 

To load the user's application resource file, Xtlnitialize performs the following steps: 

• Use XAPPLRESLANGPATH environment variable to look up the file. A possible value for 
XAPPLRESLANGDIR is: 

7%N:$HOME/app-defaults/%L/%N:$HOME/app-defaults/%N:$HOME/%L/%N:$HOME/%> 

• If that fails, or if XAPPLPRESLANGPATH is not defined, and if XAPPLRESDIR is defined, 
use the following as the path: 

%XAPPLRESDIR%L/%N:%XAPPLRESDIR%N 

• else use: 

$HOME/%L/%N:$HOME/%N 

Note that if the XAPPLRESLANGPATH lookup is not successful and LANG is not defined the 
lookup is then equivalent to that used by the R3 specification of Xtlnitialize (actually described 
under XtDisplaylnitialize). 

The parameters for Xtlnitialize are defined below: 

shelljtame Specifies the name of the application shell widget instance, which usually 

is something generic like "main." This name is used by the Xt Intrinsics 
to search for resources that belong specifically to this shell widget. The 
application name is derived from the -name command line argument or 
if that is not present the trailing component of argvfO]. 

application _class Specifies the class name of this application, which usually is the generic 

name for all instances of this application. By convention, the class name 
is formed by reversing the case of the application's first letter. The class 
name is used to locate the files used to initialize the resource database. 

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to XrmPar- 
seCommand. 

num_options Specifies the number of entries in options list 

argc Specifies a pointer to the number of command line parameters. 

argy Specifies the command line parameters. 

RETURN VALUE 

Returns the widget ID of the top-level shell. The class of the shell is Applica- 
tionShellWidgetClass. 

RELATED INFORMATION 

XtDisplayInitialize(3X). 
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NAME 

XtUngrabKey - a function that cancels a passive grab on a key combination. 

SYNOPSIS 

#include <Xll/PassivGrab.h> 

void XtUngrabKey (widget, keycode, modifiers) 
Widget widget; 
Keycode keycode; 
unsigned int modifiers; 

DESCRIPTION 

XtUngrabKey cancels the passive grab on the key combination on the specified widget and allows 
the client to redirect the specified key event to the root widget of a hierarchy. 

widget Specifies the root widget to the XtUngrabKey call. 

keycode Specifies the Keycode. This maps to the specific key to be grabbed. 

modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these key- 
mask bits: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, 
Mod3Mask, ModMMask, Mod5Mask. You can also pass AnyModifkr, which is 
equivalent to issuing the ungrab key request for all possible modifier combina- 
tions, including the combination of no modifiers. 

RELATED INFORMATION 
XtGrabKey(3X). 
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NAME 

XtUngrabKeyboard - a fiinction releases an active grab on the keyboard. 

SYNOPSIS 

#include <Xll/PassivGrab.h> 

void XtUngrabKeyboard (widget, time)) 
Widget widget} 
Time time, 

DESCRIPTION 

XtUngrabKeyboard releases any active grab on the keyboard. 

widget Specifies the root widget to the XtUngrabKeyboard call. 

time Specifies the time. You can pass either a timestamp, expressed in milliseconds, or 

CurrentTime. 



RELATED INFORMATION 

XtGrabKeyboard(3X). 
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NAME 

XtWidgetCallCallbacks - a function that invokes the entries on a callback list 



SYNOPSIS 

#include <Xm/Xm.h> 

void XtWidgetCallCallbacks (callbacks, call data) 
XtCallbackList callbacks', 
Opaque caU_data; 

DESCRIPTION 

XtWidgetCallCallbacks calls the entries on a callback list. The widget knows the address of the 
callback list and avoids extra processing by using this function. The external version of this rou- 
tine is XtCallCallbacks. 



callbacks Specifies the callback list to execute. 

call_data Specifies a callback-list specific data value to pass to each of the callback pro- 
cedures in the list 
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NAME 

XtWidgetHasCaUbacks - a function that returns the status of the specified callback list. 

SYNOPSIS 

#include <Xm/Xm.h> 

XtCallbackStatus XtWidgetHasCallbacks {callbacks) 
XtCallbackList callbacks', 

DESCRIPTION 

XtWidgetHasCallbacks returns the status of the specified callback list The external version of 
this routine is XtHasCallbacks. 

callbacks Specifies the callback list to execute. 

call _data Specifies a callback-list specific data value to pass to each of the callback pro- 
cedures in the list. 

RETURN VALUE 

Returns XtCallbackNoList if no callback list; XtCallbackHasNone if the callback list is empty, or 
XtCallbackHasSome if the callback list has at least one callback registered. 
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